griptape-nodes 0.40.0__py3-none-any.whl → 0.42.0__py3-none-any.whl

griptape_nodes/retained_mode/griptape_nodes.py

@@ -7,11 +7,10 @@ import re
 import uuid
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from typing import IO, TYPE_CHECKING, Any, TextIO
+from typing import TYPE_CHECKING, Any
 
 import httpx
 
-from griptape_nodes.exe_types.core_types import BaseNodeElement, Parameter, ParameterContainer, ParameterGroup
 from griptape_nodes.exe_types.flow import ControlFlow
 from griptape_nodes.node_library.workflow_registry import WorkflowRegistry
 from griptape_nodes.retained_mode.events.app_events import (
@@ -40,34 +39,23 @@ from griptape_nodes.retained_mode.events.app_events import (
 )
 from griptape_nodes.retained_mode.events.base_events import (
     AppPayload,
-    BaseEvent,
     RequestPayload,
     ResultPayload,
     ResultPayloadFailure,
 )
-from griptape_nodes.retained_mode.events.connection_events import (
-    CreateConnectionRequest,
-)
 from griptape_nodes.retained_mode.events.flow_events import (
-    CreateFlowRequest,
     DeleteFlowRequest,
 )
-from griptape_nodes.retained_mode.events.parameter_events import (
-    AddParameterToNodeRequest,
-    AlterParameterDetailsRequest,
-)
-from griptape_nodes.retained_mode.utils.engine_identity import EngineIdentity
-from griptape_nodes.retained_mode.utils.session_persistence import SessionPersistence
 from griptape_nodes.utils.metaclasses import SingletonMeta
 
 if TYPE_CHECKING:
-    from griptape_nodes.exe_types.node_types import BaseNode
     from griptape_nodes.retained_mode.managers.agent_manager import AgentManager
     from griptape_nodes.retained_mode.managers.arbitrary_code_exec_manager import (
         ArbitraryCodeExecManager,
     )
     from griptape_nodes.retained_mode.managers.config_manager import ConfigManager
     from griptape_nodes.retained_mode.managers.context_manager import ContextManager
+    from griptape_nodes.retained_mode.managers.engine_identity_manager import EngineIdentityManager
     from griptape_nodes.retained_mode.managers.event_manager import EventManager
     from griptape_nodes.retained_mode.managers.flow_manager import FlowManager
     from griptape_nodes.retained_mode.managers.library_manager import LibraryManager
@@ -78,6 +66,7 @@ if TYPE_CHECKING:
     )
     from griptape_nodes.retained_mode.managers.os_manager import OSManager
     from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
+    from griptape_nodes.retained_mode.managers.session_manager import SessionManager
     from griptape_nodes.retained_mode.managers.static_files_manager import (
         StaticFilesManager,
     )
@@ -147,6 +136,8 @@ class GriptapeNodes(metaclass=SingletonMeta):
     _static_files_manager: StaticFilesManager
     _agent_manager: AgentManager
     _version_compatibility_manager: VersionCompatibilityManager
+    _session_manager: SessionManager
+    _engine_identity_manager: EngineIdentityManager
 
     def __init__(self) -> None:
         from griptape_nodes.retained_mode.managers.agent_manager import AgentManager
@@ -155,6 +146,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         )
         from griptape_nodes.retained_mode.managers.config_manager import ConfigManager
         from griptape_nodes.retained_mode.managers.context_manager import ContextManager
+        from griptape_nodes.retained_mode.managers.engine_identity_manager import EngineIdentityManager
         from griptape_nodes.retained_mode.managers.event_manager import EventManager
         from griptape_nodes.retained_mode.managers.flow_manager import FlowManager
         from griptape_nodes.retained_mode.managers.library_manager import LibraryManager
@@ -165,6 +157,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         )
         from griptape_nodes.retained_mode.managers.os_manager import OSManager
         from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
+        from griptape_nodes.retained_mode.managers.session_manager import SessionManager
         from griptape_nodes.retained_mode.managers.static_files_manager import (
             StaticFilesManager,
         )
@@ -194,6 +187,8 @@ class GriptapeNodes(metaclass=SingletonMeta):
             )
             self._agent_manager = AgentManager(self._static_files_manager, self._event_manager)
             self._version_compatibility_manager = VersionCompatibilityManager(self._event_manager)
+            self._session_manager = SessionManager(self._event_manager)
+            self._engine_identity_manager = EngineIdentityManager(self._event_manager)
 
             # Assign handlers now that these are created.
             self._event_manager.assign_manager_to_request_type(
@@ -223,16 +218,23 @@ class GriptapeNodes(metaclass=SingletonMeta):
         return cls()
 
     @classmethod
-    def handle_request(cls, request: RequestPayload) -> ResultPayload:
+    def handle_request(
+        cls,
+        request: RequestPayload,
+        *,
+        response_topic: str | None = None,
+        request_id: str | None = None,
+    ) -> ResultPayload:
         event_mgr = GriptapeNodes.EventManager()
         obj_depth_mgr = GriptapeNodes.OperationDepthManager()
         workflow_mgr = GriptapeNodes.WorkflowManager()
-
         try:
             return event_mgr.handle_request(
                 request=request,
                 operation_depth_mgr=obj_depth_mgr,
                 workflow_mgr=workflow_mgr,
+                response_topic=response_topic,
+                request_id=request_id,
             )
         except Exception as e:
             logger.exception(
@@ -249,7 +251,11 @@ class GriptapeNodes(metaclass=SingletonMeta):
 
     @classmethod
     def get_session_id(cls) -> str | None:
-        return BaseEvent._session_id
+        return GriptapeNodes.SessionManager().get_active_session_id()
+
+    @classmethod
+    def get_engine_id(cls) -> str | None:
+        return GriptapeNodes.EngineIdentityManager().get_active_engine_id()
 
     @classmethod
     def EventManager(cls) -> EventManager:
@@ -307,6 +313,14 @@ class GriptapeNodes(metaclass=SingletonMeta):
     def VersionCompatibilityManager(cls) -> VersionCompatibilityManager:
         return GriptapeNodes.get_instance()._version_compatibility_manager
 
+    @classmethod
+    def SessionManager(cls) -> SessionManager:
+        return GriptapeNodes.get_instance()._session_manager
+
+    @classmethod
+    def EngineIdentityManager(cls) -> EngineIdentityManager:
+        return GriptapeNodes.get_instance()._engine_identity_manager
+
     @classmethod
     def clear_data(cls) -> None:
         # Get canvas
@@ -348,13 +362,11 @@ class GriptapeNodes(metaclass=SingletonMeta):
             return GetEngineVersionResultFailure()
 
     def handle_session_start_request(self, request: AppStartSessionRequest) -> ResultPayload:  # noqa: ARG002
-        current_session_id = BaseEvent._session_id
+        current_session_id = GriptapeNodes.SessionManager().get_active_session_id()
         if current_session_id is None:
             # Client wants a new session
             current_session_id = uuid.uuid4().hex
-            BaseEvent._session_id = current_session_id
-            # Persist the session ID to XDG state directory
-            SessionPersistence.persist_session(current_session_id)
+            GriptapeNodes.SessionManager().save_session(current_session_id)
             details = f"New session '{current_session_id}' started at {datetime.now(tz=UTC)}."
             logger.info(details)
         else:
@@ -364,16 +376,14 @@ class GriptapeNodes(metaclass=SingletonMeta):
 
     def handle_session_end_request(self, _: AppEndSessionRequest) -> ResultPayload:
         try:
-            previous_session_id = BaseEvent._session_id
-            if BaseEvent._session_id is None:
+            previous_session_id = GriptapeNodes.SessionManager().get_active_session_id()
+            if previous_session_id is None:
                 details = "No active session to end."
                 logger.info(details)
             else:
-                details = f"Session '{BaseEvent._session_id}' ended at {datetime.now(tz=UTC)}."
+                details = f"Session '{previous_session_id}' ended at {datetime.now(tz=UTC)}."
                 logger.info(details)
-                BaseEvent._session_id = None
-                # Clear the persisted session ID from XDG state directory
-                SessionPersistence.clear_persisted_session()
+                GriptapeNodes.SessionManager().clear_saved_session()
 
             return AppEndSessionResultSuccess(session_id=previous_session_id)
         except Exception as err:
@@ -382,7 +392,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
             return AppEndSessionResultFailure()
 
     def handle_get_session_request(self, _: AppGetSessionRequest) -> ResultPayload:
-        return AppGetSessionResultSuccess(session_id=BaseEvent._session_id)
+        return AppGetSessionResultSuccess(session_id=GriptapeNodes.SessionManager().get_active_session_id())
 
     def handle_session_heartbeat_request(self, request: SessionHeartbeatRequest) -> ResultPayload:  # noqa: ARG002
         """Handle session heartbeat requests.
@@ -390,11 +400,12 @@ class GriptapeNodes(metaclass=SingletonMeta):
         Simply verifies that the session is active and responds with success.
         """
         try:
-            if BaseEvent._session_id is None:
+            active_session_id = GriptapeNodes.SessionManager().get_active_session_id()
+            if active_session_id is None:
                 logger.warning("Session heartbeat received but no active session found")
                 return SessionHeartbeatResultFailure()
 
-            logger.debug("Session heartbeat successful for session: %s", BaseEvent._session_id)
+            logger.debug("Session heartbeat successful for session: %s", active_session_id)
             return SessionHeartbeatResultSuccess()
         except Exception as err:
             logger.error("Failed to handle session heartbeat: %s", err)
@@ -413,15 +424,15 @@ class GriptapeNodes(metaclass=SingletonMeta):
             workflow_info = self._get_current_workflow_info()
 
             # Get engine name
-            engine_name = EngineIdentity.get_engine_name()
+            engine_name = GriptapeNodes.EngineIdentityManager().get_engine_name()
 
             logger.debug("Engine heartbeat successful")
             return EngineHeartbeatResultSuccess(
                 heartbeat_id=request.heartbeat_id,
                 engine_version=engine_version,
                 engine_name=engine_name,
-                engine_id=BaseEvent._engine_id,
-                session_id=BaseEvent._session_id,
+                engine_id=GriptapeNodes.EngineIdentityManager().get_active_engine_id(),
+                session_id=GriptapeNodes.SessionManager().get_active_session_id(),
                 timestamp=datetime.now(tz=UTC).isoformat(),
                 **instance_info,
                 **workflow_info,
@@ -433,7 +444,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
     def handle_get_engine_name_request(self, request: GetEngineNameRequest) -> ResultPayload:  # noqa: ARG002
         """Handle requests to get the current engine name."""
         try:
-            engine_name = EngineIdentity.get_engine_name()
+            engine_name = GriptapeNodes.EngineIdentityManager().get_engine_name()
             logger.debug("Retrieved engine name: %s", engine_name)
             return GetEngineNameResultSuccess(engine_name=engine_name)
         except Exception as err:
@@ -451,7 +462,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
                 return SetEngineNameResultFailure(error_message=error_message)
 
             # Set the new engine name
-            EngineIdentity.set_engine_name(request.engine_name.strip())
+            GriptapeNodes.EngineIdentityManager().set_engine_name(request.engine_name.strip())
             logger.info("Engine name set to: %s", request.engine_name.strip())
             return SetEngineNameResultSuccess(engine_name=request.engine_name.strip())
 
@@ -543,291 +554,3 @@ class GriptapeNodes(metaclass=SingletonMeta):
             logger.warning("Failed to get current workflow info: %s", err)
 
         return workflow_info
-
-
-def create_flows_in_order(flow_name: str, flow_manager: FlowManager, created_flows: list, file: IO) -> list | None:
-    """Creates flows in the correct order based on their dependencies."""
-    # If this flow is already created, we can return
-    if flow_name in created_flows:
-        return None
-
-    # Get the parent of this flow
-    parent = flow_manager.get_parent_flow(flow_name)
-
-    # If there's a parent, create it first
-    if parent:
-        create_flows_in_order(parent, flow_manager, created_flows, file)
-
-    # Now create this flow (only if not already created)
-    if flow_name not in created_flows:
-        # Here you would actually send the request and handle response
-        creation_request = CreateFlowRequest(flow_name=flow_name, parent_flow_name=parent)
-        code_string = f"GriptapeNodes.handle_request({creation_request})"
-        file.write(code_string + "\n")
-        created_flows.append(flow_name)
-
-    return created_flows
-
-
-def handle_flow_saving(file: TextIO, obj_manager: ObjectManager, created_flows: list) -> str:
-    """Handles the creation and saving of flows."""
-    flow_manager = GriptapeNodes.FlowManager()
-    connection_request_workflows = ""
-    for flow_name, flow in obj_manager.get_filtered_subset(type=ControlFlow).items():
-        create_flows_in_order(flow_name, flow_manager, created_flows, file)
-        # While creating flows - let's create all of our connections
-        for connection in flow.connections.connections.values():
-            creation_request = CreateConnectionRequest(
-                source_node_name=connection.source_node.name,
-                source_parameter_name=connection.source_parameter.name,
-                target_node_name=connection.target_node.name,
-                target_parameter_name=connection.target_parameter.name,
-                initial_setup=True,
-            )
-            code_string = f"GriptapeNodes.handle_request({creation_request})"
-            connection_request_workflows += code_string + "\n"
-    return connection_request_workflows
-
-
-def handle_parameter_creation_saving(node: BaseNode, values_created: dict) -> tuple[str, bool]:
-    """Handles the creation and saving of parameters for a node."""
-    parameter_details = ""
-    saved_properly = True
-    # Get all parameters, even ones that aren't direct children.
-    for parameter in node.root_ui_element.find_elements_by_type(BaseNodeElement):
-        if isinstance(parameter, (Parameter, ParameterGroup, ParameterContainer)):
-            param_dict = parameter.to_dict()
-            # Create the parameter, or alter it on the existing node
-            if isinstance(parameter, Parameter) and parameter.user_defined:
-                param_dict["node_name"] = node.name
-                param_dict["initial_setup"] = True
-                creation_request = AddParameterToNodeRequest.create(**param_dict)
-                code_string = f"GriptapeNodes.handle_request({creation_request})\n"
-                parameter_details += code_string
-            else:
-                base_node_obj = type(node)(name="test")
-                diff = manage_alter_details(parameter, base_node_obj)
-                relevant = False
-                for key in diff:
-                    if key in AlterParameterDetailsRequest.relevant_parameters():
-                        relevant = True
-                        break
-                if relevant:
-                    diff["node_name"] = node.name
-                    diff["parameter_name"] = parameter.name
-                    diff["initial_setup"] = True
-                    creation_request = AlterParameterDetailsRequest.create(**diff)
-                    code_string = f"GriptapeNodes.handle_request({creation_request})\n"
-                    parameter_details += code_string
-            if not isinstance(parameter, ParameterGroup) and (
-                parameter.name in node.parameter_values or parameter.name in node.parameter_output_values
-            ):
-                # SetParameterValueRequest event
-                code_string = handle_parameter_value_saving(parameter, node, values_created)
-                if code_string:
-                    code_string = code_string + "\n"
-                    parameter_details += code_string
-                else:
-                    saved_properly = False
-    return parameter_details, saved_properly
-
-
-def handle_parameter_value_saving(parameter: Parameter, node: BaseNode, values_created: dict) -> str | None:
-    """Generates code to save a parameter value for a node in a Griptape workflow.
-
-    This function handles the process of creating code that will reconstruct and set
-    parameter values for nodes. It performs the following steps:
-    1. Retrieves the parameter value from the node's parameter values or output values
-    2. Checks if the value has already been created in the generated code
-    3. If not, generates code to reconstruct the value
-    4. Creates a SetParameterValueRequest to apply the value to the node
-
-    Args:
-        parameter (Parameter): The parameter object containing metadata
-        node (BaseNode): The node object that contains the parameter
-        values_created (dict): Dictionary mapping value identifiers to variable names
-                              that have already been created in the code
-
-    Returns:
-        str | None: Python code as a string that will reconstruct and set the parameter
-                   value when executed. Returns None if the parameter has no value or
-                   if the value cannot be properly represented.
-
-    Notes:
-        - Parameter output values take precedence over regular parameter values
-        - For values that can be hashed, the value itself is used as the key in values_created
-        - For unhashable values, the object's id is used as the key
-        - The function will reuse already created values to avoid duplication
-    """
-    value = None
-    is_output = False
-    if parameter.name in node.parameter_values:
-        value = node.get_parameter_value(parameter.name)
-    # Output values are more important
-    if parameter.name in node.parameter_output_values:
-        value = node.parameter_output_values[parameter.name]
-        is_output = True
-    if value is not None:
-        try:
-            hash(value)
-            value_id = value
-        except TypeError:
-            value_id = id(value)
-        if value_id in values_created:
-            var_name = values_created[value_id]
-            # We've already created this object. we're all good.
-            return f"GriptapeNodes.handle_request(SetParameterValueRequest(parameter_name='{parameter.name}', node_name='{node.name}', value={var_name}, initial_setup=True, is_output={is_output}))"
-        # Set it up as a object in the code
-        imports = []
-        var_name = f"{node.name}_{parameter.name}_value"
-        values_created[value_id] = var_name
-        reconstruction_code = _convert_value_to_str_representation(var_name, value, imports)
-        # If it doesn't have a custom __str__, convert to dict if possible
-        if reconstruction_code != "":
-            # Add the request handling code
-            final_code = (
-                reconstruction_code
-                + f"GriptapeNodes.handle_request(SetParameterValueRequest(parameter_name='{parameter.name}', node_name='{node.name}', value={var_name}, initial_setup=True, is_output={is_output}))"
-            )
-            # Combine imports and code
-            import_statements = ""
-            if imports:
-                import_statements = "\n".join(list(set(imports))) + "\n\n"  # Remove duplicates with set()
-            return import_statements + final_code
-    return None
-
-
-def _convert_value_to_str_representation(var_name: str, value: Any, imports: list) -> str:
-    """Converts a Python value to its string representation as executable code.
-
-    This function generates Python code that can recreate the given value
-    when executed. It handles different types of values with specific strategies:
-    - Objects with a 'to_dict' method: Uses _create_object_in_file for reconstruction
-    - Basic Python types: Uses their repr representation
-    - If not representable: Returns empty string
-
-    Args:
-        var_name (str): The variable name to assign the value to in the generated code
-        value (Any): The Python value to convert to code
-        imports (list): List to which any required import statements will be appended
-
-    Returns:
-        str: Python code as a string that will reconstruct the value when executed.
-             Returns empty string if the value cannot be properly represented.
-    """
-    reconstruction_code = ""
-    # If it doesn't have a custom __str__, convert to dict if possible
-    if hasattr(value, "to_dict") and callable(value.to_dict):
-        # For objects with to_dict method
-        reconstruction_code = _create_object_in_file(value, var_name, imports)
-        return reconstruction_code
-    if isinstance(value, (int, float, str, bool)) or value is None:
-        # For basic types, use repr to create a literal
-        return f"{var_name} = {value!r}\n"
-    if isinstance(value, (list, dict, tuple, set)):
-        reconstruction_code = _convert_container_to_str_representation(var_name, value, imports, type(value))
-        return reconstruction_code
-    return ""
-
-
-def _convert_container_to_str_representation(var_name: str, value: Any, imports: list, value_type: type) -> str:
-    """Creates code to reconstruct a container type (list, dict, tuple, set) with its elements.
-
-    Args:
-        var_name (str): The variable name to assign the container to
-        value (Any): The container value to convert to code
-        imports (list): List to which any required import statements will be appended
-        value_type (type): The type of container (list, dict, tuple, or set)
-
-    Returns:
-        str: Python code as a string that will reconstruct the container
-    """
-    # Get the initialization brackets from an empty container
-    empty_container = value_type()
-    init_brackets = repr(empty_container)
-    # Initialize the container
-    code = f"{var_name} = {init_brackets}\n"
-    temp_var_base = f"{var_name}_item"
-    if value_type is dict:
-        # Process dictionary items
-        for i, (k, v) in enumerate(value.items()):
-            temp_var = f"{temp_var_base}_{i}"
-            # Convert the value to code
-            value_code = _convert_value_to_str_representation(temp_var, v, imports)
-            if value_code:
-                code += value_code
-                code += f"{var_name}[{k!r}] = {temp_var}\n"
-            else:
-                code += f"{var_name}[{k!r}] = {v!r}\n"
-    else:
-        # Process sequence items (list, tuple, set)
-        # For immutable types like tuple and set, we need to build a list first
-        for i, item in enumerate(value):
-            temp_var = f"{temp_var_base}_{i}"
-            # Convert the item to code
-            item_code = _convert_value_to_str_representation(temp_var, item, imports)
-            if item_code != "":
-                code += item_code
-                code += f"{var_name}.append({temp_var})\n"
-            else:
-                code += f"{var_name}.append({item!r})\n"
-        # Convert the list to the final type if needed
-        if value_type in (tuple, set):
-            code += f"{var_name} = {value_type.__name__}({var_name})\n"
-    return code
-
-
-def _create_object_in_file(value: Any, var_name: str, imports: list) -> str:
-    """Creates Python code to reconstruct an object from its dictionary representation and adds necessary import statements.
-
-    Args:
-        value (Any): The object to be serialized into Python code
-        var_name (str): The name of the variable to assign the object to in the generated code
-        imports (list): List to which import statements will be appended
-
-    Returns:
-        str: Python code string that reconstructs the object when executed
-             Returns empty string if object cannot be properly reconstructed
-
-    Notes:
-        - The function assumes the object has a 'to_dict()' method to serialize it. It is only called if the object does have that method.
-        - For class instances, it will add appropriate import statements to 'imports'
-        - The generated code will create a dictionary representation first, then
-          reconstruct the object using a 'from_dict' class method
-    """
-    obj_dict = value.to_dict()
-    reconstruction_code = f"{var_name} = {obj_dict!r}\n"
-    # If we know the class, we can reconstruct it and add import
-    if hasattr(value, "__class__"):
-        class_name = value.__class__.__name__
-        module_name = value.__class__.__module__
-        if module_name != "builtins":
-            imports.append(f"from {module_name} import {class_name}")
-        reconstruction_code += f"{var_name} = {class_name}.from_dict({var_name})\n"
-        return reconstruction_code
-    return ""
-
-
-def manage_alter_details(parameter: Parameter | ParameterGroup, base_node_obj: BaseNode) -> dict:
-    """Alters the details of a parameter based on the base node object."""
-    if isinstance(parameter, Parameter):
-        base_param = base_node_obj.get_parameter_by_name(parameter.name)
-        if base_param is not None:
-            diff = base_param.equals(parameter)
-        else:
-            return vars(parameter)
-    else:
-        base_param_group = base_node_obj.get_group_by_name_or_element_id(parameter.name)
-        if base_param_group is not None:
-            diff = base_param_group.equals(parameter)
-        else:
-            return vars(parameter)
-    return diff
-
-
-def __getattr__(name: str) -> logging.Logger:
-    """Convenience function so that node authors only need to write 'logger.debug()'."""
-    if name == "logger":
-        return logger
-    msg = f"module '{__name__}' has no attribute '{name}'"
-    raise AttributeError(msg)

griptape_nodes/retained_mode/managers/agent_manager.py

@@ -109,7 +109,7 @@ class AgentManager:
             msg = f"Secret '{API_KEY_ENV_VAR}' not found"
             raise ValueError(msg)
         return NodesPromptImageGenerationTool(
-            image_generation_driver=GriptapeCloudImageGenerationDriver(api_key=api_key, model="dall-e-3"),
+            image_generation_driver=GriptapeCloudImageGenerationDriver(api_key=api_key, model="gpt-image-1"),
             static_files_manager=self.static_files_manager,
         )
 

griptape_nodes/retained_mode/managers/engine_identity_manager.py

@@ -0,0 +1,146 @@
+"""Manages engine identity state.
+
+Centralizes engine identity management, providing a consistent interface for
+engine ID and name operations.
+"""
+
+import logging
+from pathlib import Path
+
+from griptape_nodes.retained_mode.events.base_events import BaseEvent
+from griptape_nodes.retained_mode.managers.event_manager import EventManager
+from griptape_nodes.retained_mode.utils.engine_identity import EngineIdentity
+
+logger = logging.getLogger("griptape_nodes")
+
+
+class EngineIdentityManager:
+    """Manages engine identity and active engine state."""
+
+    _active_engine_id: str | None = None
+
+    def __init__(self, event_manager: EventManager | None = None) -> None:
+        """Initialize the EngineIdentityManager.
+
+        Args:
+            event_manager: The EventManager instance to use for event handling.
+        """
+        if event_manager is not None:
+            # Register event handlers here when engine events are defined
+            pass
+
+    @classmethod
+    def get_active_engine_id(cls) -> str | None:
+        """Get the active engine ID.
+
+        Returns:
+            str | None: The active engine ID or None if not set
+        """
+        return cls._active_engine_id
+
+    @classmethod
+    def set_active_engine_id(cls, engine_id: str) -> None:
+        """Set the active engine ID.
+
+        Args:
+            engine_id: The engine ID to set as active
+        """
+        cls._active_engine_id = engine_id
+        logger.debug("Set active engine ID to: %s", engine_id)
+
+    @classmethod
+    def initialize_engine_id(cls) -> str:
+        """Initialize the engine ID if not already set."""
+        if cls._active_engine_id is None:
+            engine_id = EngineIdentity.get_engine_id()
+            BaseEvent._engine_id = engine_id
+            cls._active_engine_id = engine_id
+            logger.debug("Initialized engine ID: %s", engine_id)
+
+        return cls._active_engine_id
+
+    @classmethod
+    def get_engine_data(cls) -> dict:
+        """Get the current engine data, creating default if it doesn't exist.
+
+        Returns:
+            dict: The current engine data
+        """
+        return EngineIdentity.get_engine_data()
+
+    @classmethod
+    def get_engine_name(cls) -> str:
+        """Get the engine name.
+
+        Returns:
+            str: The engine name
+        """
+        return EngineIdentity.get_engine_name()
+
+    @classmethod
+    def set_engine_name(cls, engine_name: str) -> None:
+        """Set and persist the current engine name.
+
+        Args:
+            engine_name: The new engine name to set
+        """
+        EngineIdentity.set_engine_name(engine_name)
+        logger.info("Updated engine name to: %s", engine_name)
+
+    @classmethod
+    def get_all_engines(cls) -> list[dict]:
+        """Get all registered engines.
+
+        Returns:
+            list[dict]: List of all engine data
+        """
+        return EngineIdentity.get_all_engines()
+
+    @classmethod
+    def get_default_engine_id(cls) -> str | None:
+        """Get the default engine ID.
+
+        Returns:
+            str | None: The default engine ID or None if not set
+        """
+        return EngineIdentity.get_default_engine_id()
+
+    @classmethod
+    def set_default_engine_id(cls, engine_id: str) -> None:
+        """Set the default engine ID.
+
+        Args:
+            engine_id: The engine ID to set as default
+
+        Raises:
+            ValueError: If engine_id is not found in registered engines
+        """
+        try:
+            EngineIdentity.set_default_engine_id(engine_id)
+            logger.info("Set default engine ID to: %s", engine_id)
+        except ValueError as e:
+            logger.error("Failed to set default engine ID: %s", e)
+            raise
+
+    @classmethod
+    def get_engine_data_file_path(cls) -> Path:
+        """Get the path where engine data is stored (for debugging/inspection).
+
+        Returns:
+            Path: The path to the engine data file
+        """
+        return EngineIdentity.get_engine_data_file_path()
+
+    @classmethod
+    def ensure_engine_initialized(cls) -> str:
+        """Ensure engine is initialized and return the engine ID.
+
+        Returns:
+            str: The initialized engine ID
+        """
+        cls.initialize_engine_id()
+        engine_id = cls.get_active_engine_id()
+        if engine_id is None:
+            msg = "Failed to initialize engine ID"
+            raise RuntimeError(msg)
+        return engine_id