You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by xt...@apache.org on 2025/08/20 09:59:22 UTC
(flink-agents) branch main updated: [API][Runtime]Introduce Memory Reference (#110)
This is an automated email from the ASF dual-hosted git repository.
xtsong pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/main by this push:
new 3d89f23 [API][Runtime]Introduce Memory Reference (#110)
3d89f23 is described below
commit 3d89f23ec441889560313c977173253829a63718
Author: KeGu-069 <gu...@gmail.com>
AuthorDate: Wed Aug 20 17:59:17 2025 +0800
[API][Runtime]Introduce Memory Reference (#110)
* [api][runtime][python]Introduce MemoryRef in local python runtime
* [api][runtime][java]Add MemoryRef implementation and integrate it into MemoryObject
* [runtime][python]Add MemoryRef to cross language sections and examples
---
.../flink/agents/api/context/MemoryObject.java | 13 +-
.../apache/flink/agents/api/context/MemoryRef.java | 79 ++++++++
python/flink_agents/api/memory_object.py | 27 ++-
python/flink_agents/api/memory_reference.py | 64 +++++++
python/flink_agents/api/runner_context.py | 7 +-
python/flink_agents/examples/agent_example.py | 49 +++--
python/flink_agents/examples/my_agent.py | 32 ++--
python/flink_agents/runtime/flink_memory_object.py | 33 ++--
python/flink_agents/runtime/local_memory_object.py | 44 +++--
.../runtime/tests/test_memory_reference.py | 135 ++++++++++++++
.../agents/runtime/memory/MemoryObjectImpl.java | 13 +-
.../flink/agents/runtime/memory/MemoryRefTest.java | 200 +++++++++++++++++++++
12 files changed, 620 insertions(+), 76 deletions(-)
diff --git a/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java b/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java
index f37dcf6..6d6af4b 100644
--- a/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java
+++ b/api/src/main/java/org/apache/flink/agents/api/context/MemoryObject.java
@@ -39,16 +39,27 @@ public interface MemoryObject {
*/
MemoryObject get(String path) throws Exception;
+ /**
+ * Returns a MemoryObject that represents the path of the given reference.
+ *
+ * @param ref a reference to a data item in the short-term memory
+ * @return a MemoryObject instance pointing to the referenced field. Returns null if the path of
+ * the reference does not exist.
+ * @throws Exception if an error occurs during state access
+ */
+ MemoryObject get(MemoryRef ref) throws Exception;
+
/**
* Sets the value of a direct field in the current object; any missing intermediate objects will
* be created automatically.
*
* @param path relative path from the current object to the target field
* @param value new value of the field
+ * @return a {@link MemoryRef} instance pointing to the data just set
* @throws Exception if trying to overwrite a nested object with a primitive value or set a
* MemoryObject directly
*/
- void set(String path, Object value) throws Exception;
+ MemoryRef set(String path, Object value) throws Exception;
/**
* Creates a new MemoryObject as an indirect field in the current object.
diff --git a/api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java b/api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java
new file mode 100644
index 0000000..8f0a133
--- /dev/null
+++ b/api/src/main/java/org/apache/flink/agents/api/context/MemoryRef.java
@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.flink.agents.api.context;
+
+import java.io.Serializable;
+import java.util.Objects;
+
+/**
+ * A serializable, persistent reference to a specific data item in Short-Term Memory. It acts as a
+ * lightweight pointer, containing the path of the data, allowing for efficient passing of large
+ * objects between Actions.
+ */
+public final class MemoryRef implements Serializable {
+ private static final long serialVersionUID = 1L;
+
+ private final String path;
+
+ private MemoryRef(String path) {
+ this.path = path;
+ }
+
+ /**
+ * Creates a new MemoryRef instance with the given path.
+ *
+ * @param path The absolute path of the data in Short-Term Memory.
+ * @return A new MemoryRef instance.
+ */
+ public static MemoryRef create(String path) {
+ return new MemoryRef(path);
+ }
+
+ /**
+ * Resolves the reference using the provided RunnerContext to get the actual data.
+ *
+ * @param ctx The current execution context, used to access Short-Term Memory.
+ * @return The deserialized, original data object.
+ * @throws Exception if the memory cannot be accessed or the data cannot be resolved.
+ */
+ public MemoryObject resolve(RunnerContext ctx) throws Exception {
+ return ctx.getShortTermMemory().get(this);
+ }
+
+ public String getPath() {
+ return path;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) return true;
+ if (o == null || getClass() != o.getClass()) return false;
+ MemoryRef memoryRef = (MemoryRef) o;
+ return path.equals(memoryRef.path);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(path);
+ }
+
+ @Override
+ public String toString() {
+ return "MemoryRef{" + "path='" + path + '\'' + '}';
+ }
+}
diff --git a/python/flink_agents/api/memory_object.py b/python/flink_agents/api/memory_object.py
index 8a66e77..a250199 100644
--- a/python/flink_agents/api/memory_object.py
+++ b/python/flink_agents/api/memory_object.py
@@ -16,10 +16,12 @@
# limitations under the License.
#################################################################################
from abc import ABC, abstractmethod
-from typing import Any, Dict, List
+from typing import TYPE_CHECKING, Any, Dict, List, Union
from pydantic import BaseModel
+if TYPE_CHECKING:
+ from flink_agents.api.memory_reference import MemoryRef
class MemoryObject(BaseModel, ABC):
"""Representation of an object in the short-term memory.
@@ -30,25 +32,27 @@ class MemoryObject(BaseModel, ABC):
"""
@abstractmethod
- def get(self, path: str) -> Any:
- """Get the value of a (direct or indirect) field in the object.
+ def get(self, path_or_ref: Union[str,"MemoryRef"] ) -> Any:
+ """Get the value of a (direct or indirect) field or a MemoryRef in the object.
Parameters
----------
- path: str
- Relative path from the current object to the target field.
+ path_or_ref: Union[str,MemoryRef]
+ Relative path from the current object to the target field or
+ a MemoryRef instance.
Returns:
-------
Any
- If the field is a direct field, returns the concrete data stored.
+ If the input is a MemoryRef, resolve the reference and returns the data.
+ If the field is a direct field, return the concrete data stored.
If the field is an indirect field, another MemoryObject will be returned.
- If the field doesn't exist, returns None.
+ If the field doesn't exist, return None.
"""
@abstractmethod
- def set(self, path: str, value: Any) -> None:
- """Set the value of an indirect field in the object.
+ def set(self, path: str, value: Any) -> "MemoryRef":
+ """Set the value of a direct field in the object and return a reference to it.
This will also create the intermediate objects if not exist.
Parameters
@@ -57,6 +61,11 @@ class MemoryObject(BaseModel, ABC):
Relative path from the current object to the target field.
value: Any
New value of the field. The type of the value must be a primary type.
+
+ Returns:
+ -------
+ MemoryRef
+ A newly created reference to the data just set.
"""
@abstractmethod
diff --git a/python/flink_agents/api/memory_reference.py b/python/flink_agents/api/memory_reference.py
new file mode 100644
index 0000000..0b9d403
--- /dev/null
+++ b/python/flink_agents/api/memory_reference.py
@@ -0,0 +1,64 @@
+################################################################################
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#################################################################################
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+ from flink_agents.api.runner_context import RunnerContext
+
+
+class MemoryRef(BaseModel):
+ """Reference to a specific data item in the Short-Term Memory."""
+
+ path: str
+
+ model_config = ConfigDict(frozen=True)
+
+ @staticmethod
+ def create(path: str) -> MemoryRef:
+ """Create a new MemoryRef instance based on the given path.
+
+ Parameters
+ ----------
+ path: str
+ The absolute path of the data in the Short-Term Memory.
+
+ Returns:
+ -------
+ MemoryRef
+ A new MemoryRef instance.
+ """
+ return MemoryRef(path=path)
+
+ def resolve(self, ctx: RunnerContext) -> Any:
+ """Resolve the reference to get the actual data.
+
+ Parameters
+ ----------
+ ctx: RunnerContext
+ The current execution context, used to access Short-Term Memory.
+
+ Returns:
+ -------
+ Any
+ The deserialized, original data object.
+ """
+ return ctx.get_short_term_memory().get(self)
diff --git a/python/flink_agents/api/runner_context.py b/python/flink_agents/api/runner_context.py
index 7f938f9..03e7954 100644
--- a/python/flink_agents/api/runner_context.py
+++ b/python/flink_agents/api/runner_context.py
@@ -16,13 +16,14 @@
# limitations under the License.
#################################################################################
from abc import ABC, abstractmethod
-from typing import Any, Callable, Dict, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Dict, Tuple
from flink_agents.api.events.event import Event
-from flink_agents.api.memory_object import MemoryObject
from flink_agents.api.metric_group import MetricGroup
from flink_agents.api.resource import Resource, ResourceType
+if TYPE_CHECKING:
+ from flink_agents.api.memory_object import MemoryObject
class RunnerContext(ABC):
"""Abstract base class providing context for agent execution.
@@ -53,7 +54,7 @@ class RunnerContext(ABC):
"""
@abstractmethod
- def get_short_term_memory(self) -> MemoryObject:
+ def get_short_term_memory(self) -> "MemoryObject":
"""Get the short-term memory.
Returns:
diff --git a/python/flink_agents/examples/agent_example.py b/python/flink_agents/examples/agent_example.py
index 56487cb..613c6bb 100644
--- a/python/flink_agents/examples/agent_example.py
+++ b/python/flink_agents/examples/agent_example.py
@@ -15,7 +15,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#################################################################################
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
from flink_agents.api.agent import Agent
from flink_agents.api.decorators import action
@@ -23,6 +25,13 @@ from flink_agents.api.events.event import Event, InputEvent, OutputEvent
from flink_agents.api.execution_environment import AgentsExecutionEnvironment
from flink_agents.api.runner_context import RunnerContext
+if TYPE_CHECKING:
+ from flink_agents.api.memory_reference import MemoryRef
+
+
+class ProcessedData(BaseModel): # noqa D101
+ content: str
+ visit_count: int
class MyEvent(Event): # noqa D101
value: Any
@@ -39,33 +48,43 @@ class MyAgent(Agent):
@action(InputEvent)
@staticmethod
def first_action(event: Event, ctx: RunnerContext): # noqa D102
- input = event.input
+ key = ctx.key
+ input_message = event.input
memory = ctx.get_short_term_memory()
- current_count = memory.get("action_counter") or 0
+ data_path = f"user_data.{key}"
+ previous_data: ProcessedData = memory.get(data_path)
+ current_count = previous_data.visit_count if previous_data else 0
new_count = current_count + 1
- memory.set("action_counter", new_count)
- content = input + " -> first_action"
- key_with_count = f"(seen {new_count} times)"
+ data_to_store = ProcessedData(content=input_message,visit_count=new_count)
+ data_ref = memory.set(data_path, data_to_store)
+
+ ctx.send_event(MyEvent(value=data_ref))
+
+ processed_content = f"{input_message} -> processed_by_first_action"
+ key_with_count = f"(visit {new_count} times)"
+ ctx.send_event(OutputEvent(output={key_with_count:processed_content}))
- ctx.send_event(MyEvent(value=content))
- ctx.send_event(OutputEvent(output={key_with_count: content}))
@action(MyEvent)
@staticmethod
def second_action(event: Event, ctx: RunnerContext): # noqa D102
- input = event.value
+ content_ref: MemoryRef = event.value
memory = ctx.get_short_term_memory()
- current_count = memory.get("action_counter")
+ processed_data: ProcessedData = memory.get(content_ref)
+
+ base_message = processed_data.content
+ current_count = processed_data.visit_count
new_count = current_count + 1
- memory.set("action_counter", new_count)
- base_message = input.split("->")[0].strip()
- content = base_message + " -> second_action"
- key_with_count = f"(seen {new_count} times)"
- ctx.send_event(OutputEvent(output={key_with_count: content}))
+ updated_data_to_store = ProcessedData(content=base_message, visit_count=new_count)
+ memory.set(content_ref.path, updated_data_to_store)
+
+ final_content = f"{base_message} -> processed by second_action"
+ key_with_count = f"(visit {new_count} times)"
+ ctx.send_event(OutputEvent(output={key_with_count: final_content}))
if __name__ == "__main__":
diff --git a/python/flink_agents/examples/my_agent.py b/python/flink_agents/examples/my_agent.py
index ff90788..f13a739 100644
--- a/python/flink_agents/examples/my_agent.py
+++ b/python/flink_agents/examples/my_agent.py
@@ -51,7 +51,6 @@ class ItemData(BaseModel):
class MyEvent(Event): # noqa D101
value: Any
-
class DataStreamAgent(Agent):
"""Agent used for explaining integrating agents with DataStream.
@@ -86,38 +85,33 @@ class DataStreamAgent(Agent):
print(f"[log_to_stdout] Logging input={input}, total reviews now={total}")
return True
- input = event.input
-
+ input_data = event.input
stm = ctx.get_short_term_memory()
- status = stm.new_object("status", overwrite=True)
- total = 0
- if stm.is_exist("status.total_reviews"):
- total = status.get("total_reviews")
- total += 1
- status.set("total_reviews", total)
+ current_total = stm.get("status.total_reviews") or 0
+ total = current_total + 1
+ stm.set("status.total_reviews", total)
- log_success = yield from ctx.execute_async(log_to_stdout, input, total)
+ log_success = yield from ctx.execute_async(log_to_stdout, input_data, total)
- content = copy.deepcopy(input)
+ content = copy.deepcopy(input_data)
content.review += " first action, log success=" + str(log_success) + ","
- ctx.send_event(MyEvent(value=content))
+ content.memory_info = {"total_reviews": total}
+
+ data_ref = stm.set(f"processed_items.item_{content.id}", content)
+ ctx.send_event(MyEvent(value=data_ref.model_dump()))
@action(MyEvent)
@staticmethod
def second_action(event: Event, ctx: RunnerContext): # noqa D102
- input = event.value
-
+ input_data = event.value
stm = ctx.get_short_term_memory()
- memory_info = {
- "total_reviews": stm.get("status.total_reviews"),
- }
+ resolved_data: ItemData = stm.get(input_data)
- content = copy.deepcopy(input)
+ content = copy.deepcopy(resolved_data)
content.review += " second action"
tool = ctx.get_resource("my_tool", ResourceType.TOOL)
content.review = tool.call(content.review)
- content.memory_info = memory_info
ctx.send_event(OutputEvent(output=content))
diff --git a/python/flink_agents/runtime/flink_memory_object.py b/python/flink_agents/runtime/flink_memory_object.py
index afd5d95..c125648 100644
--- a/python/flink_agents/runtime/flink_memory_object.py
+++ b/python/flink_agents/runtime/flink_memory_object.py
@@ -15,7 +15,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#################################################################################
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Union
+
+from python.flink_agents.api.memory_reference import MemoryRef
from flink_agents.api.memory_object import MemoryObject
@@ -32,27 +34,36 @@ class FlinkMemoryObject(MemoryObject):
"""Initialize with a Java MemoryObject instance."""
self._j_memory_object = j_memory_object
- def get(self, path: str) -> Any:
- """Get a nested object or value by path.
+ def get(self, path_or_ref: Union[str, MemoryRef]) -> Any:
+ """Get a nested object or value by path or MemoryRef.
- If the field is an object, returns a new FlinkMemoryObject.
- Returns None if the field does not exist.
+ If the input is a MemoryRef, resolve the reference and return the data.
+ If the field is a direct field, return the concrete data stored.
+ If the field is an indirect object, return a new FlinkMemoryObject.
+ Return None if the field does not exist.
"""
try:
- j_result = self._j_memory_object.get(path)
+ path_to_get: str
+ if isinstance(path_or_ref, dict) and 'path' in path_or_ref:
+ path_to_get = path_or_ref['path']
+ elif isinstance(path_or_ref, str):
+ path_to_get = path_or_ref
+ j_result = self._j_memory_object.get(path_to_get)
if j_result is None:
return None
- if not j_result.isNestedObject():
+ if j_result.isNestedObject():
+ return FlinkMemoryObject(j_result)
+ else:
return j_result.getValue()
- return FlinkMemoryObject(j_result)
except Exception as e:
- msg = f"Failed to get field '{path}' from short-term memory"
+ msg = f"Failed to get field '{path_or_ref}' from short-term memory"
raise MemoryObjectError(msg) from e
- def set(self, path: str, value: Any) -> None:
+ def set(self, path: str, value: Any) -> MemoryRef:
"""Set a value at the given path. Creates intermediate objects if needed."""
try:
- self._j_memory_object.set(path, value)
+ j_ref = self._j_memory_object.set(path, value)
+ return MemoryRef(path=j_ref.getPath())
except Exception as e:
msg = f"Failed to set value at path '{path}'"
raise MemoryObjectError(msg) from e
diff --git a/python/flink_agents/runtime/local_memory_object.py b/python/flink_agents/runtime/local_memory_object.py
index 2925468..2b145df 100644
--- a/python/flink_agents/runtime/local_memory_object.py
+++ b/python/flink_agents/runtime/local_memory_object.py
@@ -15,9 +15,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#################################################################################
-from typing import Any, ClassVar, Dict, List
+from typing import Any, ClassVar, Dict, List, Union
from flink_agents.api.memory_object import MemoryObject
+from flink_agents.api.memory_reference import MemoryRef
class LocalMemoryObject(MemoryObject):
@@ -53,22 +54,28 @@ class LocalMemoryObject(MemoryObject):
if self.ROOT_KEY not in self.__store:
self.__store[self.ROOT_KEY] = _ObjMarker()
- def get(self, path: str) -> Any:
- """Get the value of a (direct or indirect) field in the object.
+ def get(self, path_or_ref: Union[str,MemoryRef]) -> Any:
+ """Get the value of a (direct or indirect) field or a MemoryRef in the object.
Parameters
----------
- path: str
- Relative path from the current object to the target field.
+ path_or_ref: Union[str,MemoryRef]
+ Relative path from the current object to the target field or
+ a MemoryRef instance.
Returns:
-------
Any
- If the field is a direct field, returns the concrete data stored.
+ If the input is a MemoryRef, resolve the reference and return the data.
+ If the field is a direct field, return the concrete data stored.
If the field is an indirect field, another MemoryObject will be returned.
- If the field doesn't exist, returns None.
+ If the field doesn't exist, return None.
"""
- abs_path = self._full_path(path)
+ if isinstance(path_or_ref, MemoryRef):
+ abs_path = path_or_ref.path
+ else:
+ abs_path = self._full_path(path_or_ref)
+
if abs_path in self.__store:
value = self.__store[abs_path]
if self._is_nested_object(value):
@@ -76,8 +83,8 @@ class LocalMemoryObject(MemoryObject):
return value
return None
- def set(self, path: str, value: Any) -> None:
- """Set the value of a direct field in the object.
+ def set(self, path: str, value: Any) -> MemoryRef:
+ """Set the value of a direct field in the object and return a reference to it.
This will also create the intermediate objects if not exist.
Parameters
@@ -86,24 +93,29 @@ class LocalMemoryObject(MemoryObject):
Relative path from the current object to the target field.
value: Any
New value of the field. The type of the value must be a primary type.
+
+ Returns:
+ -------
+ MemoryRef
+ A newly created reference to the data just set.
"""
if isinstance(value, LocalMemoryObject):
msg = "Do not set a MemoryObject instance directly; use new_object()."
raise TypeError(msg)
abs_path = self._full_path(path)
- parts = abs_path.split(self.__SEPARATOR)
-
- self._fill_parents(parts)
-
- parent_path = self._parent_of(parts)
- self._add_subfield(parent_path, parts[-1])
if abs_path in self.__store and self._is_nested_object(self.__store[abs_path]):
msg = f"Cannot overwrite object field '{abs_path}' with primitive."
raise ValueError(msg)
+ parts = abs_path.split(self.__SEPARATOR)
+ self._fill_parents(parts)
+ parent_path = self._parent_of(parts)
+ self._add_subfield(parent_path, parts[-1])
+
self.__store[abs_path] = value
+ return MemoryRef(path=abs_path)
def new_object(self, path: str, *, overwrite: bool = False) -> "LocalMemoryObject":
"""Create a new object as the value of an indirect field in the object.
diff --git a/python/flink_agents/runtime/tests/test_memory_reference.py b/python/flink_agents/runtime/tests/test_memory_reference.py
new file mode 100644
index 0000000..8c5e395
--- /dev/null
+++ b/python/flink_agents/runtime/tests/test_memory_reference.py
@@ -0,0 +1,135 @@
+################################################################################
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#################################################################################
+from flink_agents.api.memory_reference import MemoryRef
+from flink_agents.runtime.local_memory_object import LocalMemoryObject
+
+
+class MockRunnerContext: # noqa D101
+ def __init__(self, memory: LocalMemoryObject) -> None:
+ """Mock RunnerContext for testing resolve() method."""
+ self._memory = memory
+
+ def get_short_term_memory(self) -> LocalMemoryObject: # noqa D102
+ return self._memory
+
+
+def create_memory() -> LocalMemoryObject:
+ """Return a MemoryObject for every test case."""
+ return LocalMemoryObject({})
+
+
+class User: # noqa: D101
+ def __init__(self, name: str, age: int) -> None:
+ """Store for later comparison."""
+ self.name = name
+ self.age = age
+
+ def __eq__(self, other: object) -> bool:
+ return (
+ isinstance(other, User)
+ and other.name == self.name
+ and other.age == self.age
+ )
+
+
+def test_set_get_involved_ref() -> None: # noqa: D103
+ mem = create_memory()
+
+ # Test cases: (path, value, type_name)
+ test_cases = [
+ ("my_int", 1, "int"),
+ ("my_float", 3.14, "float"),
+ ("my_str", "hello", "str"),
+ ("my_list", ["a", "b"], "list"),
+ ("my_dict", {"x": 10}, "dict"),
+ ("my_set", {1, 2, 3}, "set"),
+ ("my_user", User("Alice", 30), "User"),
+ ]
+
+ for path, value, _expected_type_name in test_cases:
+ ref = mem.set(path, value)
+ assert isinstance(ref, MemoryRef)
+ assert ref.path == path
+
+ retrieved_value = mem.get(ref)
+ assert retrieved_value == value
+
+
+def test_memory_ref_create() -> None: # noqa: D103
+ path = "a.b.c"
+ ref = MemoryRef.create(path)
+
+ assert isinstance(ref, MemoryRef)
+ assert ref.path == path
+
+
+def test_memory_ref_resolve() -> None: # noqa: D103
+ mem = create_memory()
+ ctx = MockRunnerContext(mem)
+
+ test_data = {
+ "my_int": 1,
+ "my_float": 3.14,
+ "my_str": "hello",
+ "my_list": ["a", "b"],
+ "my_dict": {"x": 10},
+ "my_set": {1, 2, 3},
+ "my_user": User("Charlie", 50),
+ }
+
+ for path, value in test_data.items():
+ ref = mem.set(path, value)
+ resolved_value = ref.resolve(ctx)
+ assert resolved_value == value
+
+
+def test_get_with_ref_to_nested_object() -> None: # noqa: D103
+ mem = create_memory()
+ obj = mem.new_object("a.b")
+ obj.set("c", 10)
+
+ ref = MemoryRef.create("a")
+
+ resolved_obj = mem.get(ref)
+ assert isinstance(resolved_obj, LocalMemoryObject)
+ assert resolved_obj.get("b.c") == 10
+
+
+def test_get_with_non_existent_ref() -> None: # noqa: D103
+ mem = create_memory()
+
+ non_existent_ref = MemoryRef.create("this.path.does.not.exist")
+
+ assert mem.get(non_existent_ref) is None
+
+
+def test_ref_equality_and_hashing() -> None: # noqa: D103
+ ref1 = MemoryRef(path="a.b")
+ ref2 = MemoryRef(path="a.b")
+ ref3 = MemoryRef(path="a.c")
+
+ assert ref1 == ref2
+ assert ref1 != ref3
+
+ assert hash(ref1) == hash(ref2)
+ assert hash(ref1) != hash(ref3)
+
+ ref_set = {ref1, ref2, ref3}
+ assert len(ref_set) == 2
+ assert ref1 in ref_set
+ assert ref3 in ref_set
diff --git a/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java b/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java
index dfedf1f..6999e07 100644
--- a/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java
+++ b/runtime/src/main/java/org/apache/flink/agents/runtime/memory/MemoryObjectImpl.java
@@ -18,8 +18,10 @@
package org.apache.flink.agents.runtime.memory;
import org.apache.flink.agents.api.context.MemoryObject;
+import org.apache.flink.agents.api.context.MemoryRef;
import org.apache.flink.api.common.state.MapState;
+import java.io.Serializable;
import java.util.*;
public class MemoryObjectImpl implements MemoryObject {
@@ -62,7 +64,12 @@ public class MemoryObjectImpl implements MemoryObject {
}
@Override
- public void set(String path, Object value) throws Exception {
+ public MemoryObject get(MemoryRef ref) throws Exception {
+ return get(ref.getPath());
+ }
+
+ @Override
+ public MemoryRef set(String path, Object value) throws Exception {
mailboxThreadChecker.run();
String absPath = fullPath(path);
String[] parts = absPath.split("\\.");
@@ -83,6 +90,8 @@ public class MemoryObjectImpl implements MemoryObject {
MemoryItem val = new MemoryItem(value);
store.put(absPath, val);
+
+ return MemoryRef.create(absPath);
}
@Override
@@ -197,7 +206,7 @@ public class MemoryObjectImpl implements MemoryObject {
}
/** Represents an item (nested object or primitive value) stored in the short-term memory. */
- public static final class MemoryItem {
+ public static final class MemoryItem implements Serializable {
private final ItemType type;
private final Object value;
private final Set<String> subKeys;
diff --git a/runtime/src/test/java/org/apache/flink/agents/runtime/memory/MemoryRefTest.java b/runtime/src/test/java/org/apache/flink/agents/runtime/memory/MemoryRefTest.java
new file mode 100644
index 0000000..2b95f37
--- /dev/null
+++ b/runtime/src/test/java/org/apache/flink/agents/runtime/memory/MemoryRefTest.java
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.flink.agents.runtime.memory;
+
+import org.apache.flink.agents.api.context.MemoryObject;
+import org.apache.flink.agents.api.context.MemoryRef;
+import org.apache.flink.agents.api.context.RunnerContext;
+import org.apache.flink.agents.api.metrics.FlinkAgentsMetricGroup;
+import org.apache.flink.agents.api.resource.Resource;
+import org.apache.flink.agents.api.resource.ResourceType;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/** Tests for {@link MemoryRef} and its integration with {@link MemoryObject}. */
+public class MemoryRefTest {
+
+ private MemoryObjectImpl memory;
+
+ /** Simple POJO example. */
+ static class Person {
+ String name;
+ int age;
+
+ Person(String n, int a) {
+ this.name = n;
+ this.age = a;
+ }
+
+ @Override
+ public boolean equals(Object o) {
+ if (this == o) return true;
+ if (!(o instanceof Person)) return false;
+ Person p = (Person) o;
+ return age == p.age && Objects.equals(name, p.name);
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(name, age);
+ }
+ }
+
+ /** Mock RunnerContext for testing resolve(). */
+ static class MockRunnerContext implements RunnerContext {
+ private final MemoryObject memoryObject;
+
+ MockRunnerContext(MemoryObject memoryObject) {
+ this.memoryObject = memoryObject;
+ }
+
+ @Override
+ public MemoryObject getShortTermMemory() {
+ return memoryObject;
+ }
+
+ @Override
+ public void sendEvent(org.apache.flink.agents.api.Event event) {}
+
+ @Override
+ public FlinkAgentsMetricGroup getAgentMetricGroup() {
+ return null;
+ }
+
+ @Override
+ public FlinkAgentsMetricGroup getActionMetricGroup() {
+ return null;
+ }
+
+ @Override
+ public Resource getResource(String name, ResourceType type) throws Exception {
+ return null;
+ }
+ }
+
+ @BeforeEach
+ void setUp() throws Exception {
+ ForTestMemoryMapState<MemoryObjectImpl.MemoryItem> mapState = new ForTestMemoryMapState<>();
+ memory = new MemoryObjectImpl(mapState, MemoryObjectImpl.ROOT_KEY);
+ }
+
+ @Test
+ void testSetAndGetInvolvedRef() throws Exception {
+ MemoryRef intRef = memory.set("my_int", 123);
+ assertEquals("my_int", intRef.getPath());
+ assertEquals(123, memory.get(intRef).getValue());
+
+ MemoryRef strRef = memory.set("my_str", "hello");
+ assertEquals("my_str", strRef.getPath());
+ assertEquals("hello", memory.get(strRef).getValue());
+
+ // List
+ List<String> list = Arrays.asList("a", "b");
+ MemoryRef listRef = memory.set("my_list", list);
+ assertEquals("my_list", listRef.getPath());
+ assertEquals(list, memory.get(listRef).getValue());
+
+ // Map
+ Map<String, Integer> map = new HashMap<>();
+ map.put("x", 10);
+ MemoryRef mapRef = memory.set("my_map", map);
+ assertEquals("my_map", mapRef.getPath());
+ assertEquals(map, memory.get(mapRef).getValue());
+
+ // Set
+ Set<Integer> set = new HashSet<>(Arrays.asList(1, 2, 3));
+ MemoryRef setRef = memory.set("my_set", set);
+ assertEquals("my_set", setRef.getPath());
+ assertEquals(set, memory.get(setRef).getValue());
+
+ // Custom POJO
+ Person alice = new Person("Alice", 23);
+ MemoryRef personRef = memory.set("pojo", alice);
+ assertEquals("pojo", personRef.getPath());
+ assertEquals(alice, memory.get(personRef).getValue());
+ }
+
+ @Test
+ void testMemoryRefCreate() {
+ String path = "a.b.c";
+ String typeName = "String";
+ MemoryRef ref = MemoryRef.create(path);
+
+ assertNotNull(ref);
+ assertEquals(path, ref.getPath());
+ }
+
+ @Test
+ void testMemoryRefResolve() throws Exception {
+ MockRunnerContext ctx = new MockRunnerContext(memory);
+
+ Map<String, Object> testData = new HashMap<>();
+ testData.put("my_int", 1);
+ testData.put("my_str", "resolve_test");
+ testData.put("my_list", Arrays.asList("x", "y", "z"));
+ testData.put("my_person", new Person("Resolver", 42));
+
+ for (Map.Entry<String, Object> entry : testData.entrySet()) {
+ MemoryRef ref = memory.set(entry.getKey(), entry.getValue());
+
+ Object resolvedValue = ref.resolve(ctx).getValue();
+ assertEquals(entry.getValue(), resolvedValue);
+ }
+ }
+
+ @Test
+ void testGetWithRefToNestedObject() throws Exception {
+ MemoryObject obj = memory.newObject("a.b", false);
+ obj.set("c", 10);
+
+ MemoryRef ref = MemoryRef.create("a");
+
+ MemoryObject resolvedObj = memory.get(ref);
+ assertNotNull(resolvedObj);
+ assertTrue(resolvedObj.isNestedObject());
+ assertEquals(10, resolvedObj.get("b.c").getValue());
+ }
+
+ @Test
+ void testGetWithNonExistentRef() throws Exception {
+ MemoryRef nonExistentRef = MemoryRef.create("this.path.does.not.exist");
+ assertNull(memory.get(nonExistentRef));
+ }
+
+ @Test
+ void testRefEqualityAndHashing() {
+ MemoryRef ref1 = MemoryRef.create("a.b");
+ MemoryRef ref2 = MemoryRef.create("a.b");
+ MemoryRef ref3 = MemoryRef.create("a.c");
+
+ assertEquals(ref1, ref2);
+ assertNotEquals(ref1, ref3);
+
+ assertEquals(ref1.hashCode(), ref2.hashCode());
+ assertNotEquals(ref1.hashCode(), ref3.hashCode());
+
+ Set<MemoryRef> refSet = new HashSet<>(Arrays.asList(ref1, ref2, ref3));
+ assertEquals(2, refSet.size());
+ assertTrue(refSet.contains(ref1));
+ assertTrue(refSet.contains(ref3));
+ }
+}