griptape-nodes 0.41.0__py3-none-any.whl → 0.43.0__py3-none-any.whl

griptape_nodes/retained_mode/events/agent_events.py

@@ -21,6 +21,18 @@ class RunAgentRequestArtifact(dict):
 @dataclass
 @PayloadRegistry.register
 class RunAgentRequest(RequestPayload):
+    """Run an agent with input and optional artifacts.
+
+    Use when: Executing conversational AI interactions, processing user queries,
+    running autonomous agents, handling multi-modal inputs with URLs.
+
+    Args:
+        input: Text input to send to the agent
+        url_artifacts: List of URL artifacts to include with the request
+
+    Results: RunAgentResultStarted -> RunAgentResultSuccess (with output) | RunAgentResultFailure (execution error)
+    """
+
     input: str
     url_artifacts: list[RunAgentRequestArtifact]
 
@@ -28,76 +40,126 @@ class RunAgentRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class RunAgentResultStarted(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Agent execution started successfully. Execution will continue asynchronously."""
 
 
 @dataclass
 @PayloadRegistry.register
 class RunAgentResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Agent execution completed successfully.
+
+    Args:
+        output: Dictionary containing agent response and execution results
+    """
+
     output: dict
 
 
 @dataclass
 @PayloadRegistry.register
 class RunAgentResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Agent execution failed.
+
+    Args:
+        error: Dictionary containing error details and failure information
+    """
+
     error: dict
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConversationMemoryRequest(RequestPayload):
-    pass
+    """Get the agent's conversation memory.
+
+    Use when: Reviewing conversation history, implementing memory inspection,
+    debugging agent behavior, displaying conversation context.
+
+    Results: GetConversationMemoryResultSuccess (with runs) | GetConversationMemoryResultFailure (memory error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConversationMemoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Conversation memory retrieved successfully.
+
+    Args:
+        runs: List of conversation runs (exchanges between user and agent)
+    """
+
     runs: list[Run]
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConversationMemoryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Conversation memory retrieval failed. Common causes: memory not initialized, access error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ConfigureAgentRequest(RequestPayload):
+    """Configure agent settings and behavior.
+
+    Use when: Setting up agent parameters, changing model configurations,
+    customizing agent behavior, updating agent settings.
+
+    Args:
+        prompt_driver: Dictionary of prompt driver configuration options
+
+    Results: ConfigureAgentResultSuccess | ConfigureAgentResultFailure (configuration error)
+    """
+
     prompt_driver: dict = field(default_factory=dict)
 
 
 @dataclass
 @PayloadRegistry.register
 class ConfigureAgentResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Agent configured successfully. New settings are now active."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ConfigureAgentResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Agent configuration failed. Common causes: invalid parameters, configuration error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ResetAgentConversationMemoryRequest(RequestPayload):
-    pass
+    """Reset the agent's conversation memory.
+
+    Use when: Starting fresh conversations, clearing conversation history,
+    resolving memory issues, implementing conversation reset features.
+
+    Results: ResetAgentConversationMemoryResultSuccess | ResetAgentConversationMemoryResultFailure (reset error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class ResetAgentConversationMemoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Agent conversation memory reset successfully. All previous conversation history cleared."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ResetAgentConversationMemoryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Agent conversation memory reset failed. Common causes: memory access error, system constraints."""
 
 
 @dataclass
 @PayloadRegistry.register
 class AgentStreamEvent(ExecutionPayload):
+    """Streaming token event during agent execution.
+
+    Use when: Implementing real-time agent output, displaying progressive responses,
+    building streaming UIs, monitoring agent token generation.
+
+    Args:
+        token: Individual token generated by the agent during execution
+    """
+
     token: str

griptape_nodes/retained_mode/events/app_events.py

@@ -13,6 +13,17 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class AppStartSessionRequest(RequestPayload):
+    """Start a new application session.
+
+    Use when: Initializing client connections, beginning new workflow sessions,
+    setting up isolated execution environments, managing session state.
+
+    Args:
+        session_id: Specific session ID to use (None for auto-generated)
+
+    Results: AppStartSessionResultSuccess (with session ID) | AppStartSessionResultFailure (session creation error)
+    """
+
     # TODO: https://github.com/griptape-ai/griptape-nodes/issues/1600
     session_id: str | None = None
 
@@ -20,48 +31,86 @@ class AppStartSessionRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class AppStartSessionResultSuccess(ResultPayloadSuccess):
+    """Session started successfully.
+
+    Args:
+        session_id: Unique identifier for the created session
+    """
+
     session_id: str
 
 
 @dataclass
 @PayloadRegistry.register
 class AppStartSessionResultFailure(ResultPayloadFailure):
-    pass
+    """Session start failed. Common causes: resource constraints, initialization error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class AppGetSessionRequest(RequestPayload):
-    pass
+    """Get the current session information.
+
+    Use when: Checking session status, retrieving session details,
+    validating session state, debugging session issues.
+
+    Results: AppGetSessionResultSuccess (with session ID) | AppGetSessionResultFailure (session error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class AppGetSessionResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Session information retrieved successfully.
+
+    Args:
+        session_id: Current session identifier (None if no active session)
+    """
+
     session_id: str | None
 
 
 @dataclass
 @PayloadRegistry.register
 class AppGetSessionResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Session information retrieval failed. Common causes: session not found, access error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class AppInitializationComplete(AppPayload):
-    pass
+    """Application initialization completed successfully. All subsystems ready."""
+
+
+@dataclass
+@PayloadRegistry.register
+class AppConnectionEstablished(AppPayload):
+    """Notification that a connection to the API has been established."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetEngineVersionRequest(RequestPayload):
-    pass
+    """Get the engine version information.
+
+    Use when: Checking compatibility, displaying version info,
+    debugging engine issues, validating engine capabilities.
+
+    Results: GetEngineVersionResultSuccess (with version numbers) | GetEngineVersionResultFailure (version error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetEngineVersionResultSuccess(ResultPayloadSuccess):
+    """Engine version retrieved successfully.
+
+    Args:
+        major: Major version number
+        minor: Minor version number
+        patch: Patch version number
+    """
+
     major: int
     minor: int
     patch: int
@@ -70,25 +119,37 @@ class GetEngineVersionResultSuccess(ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class GetEngineVersionResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Engine version retrieval failed. Common causes: version not available, system error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class AppEndSessionRequest(RequestPayload):
-    pass
+    """End the current application session.
+
+    Use when: Closing client connections, cleaning up session resources,
+    terminating workflow sessions, implementing logout functionality.
+
+    Results: AppEndSessionResultSuccess (with session ID) | AppEndSessionResultFailure (cleanup error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class AppEndSessionResultSuccess(ResultPayloadSuccess):
+    """Session ended successfully.
+
+    Args:
+        session_id: Identifier of the ended session (None if no session was active)
+    """
+
     session_id: str | None
 
 
 @dataclass
 @PayloadRegistry.register
 class AppEndSessionResultFailure(ResultPayloadFailure):
-    pass
+    """Session end failed. Common causes: session not found, cleanup error."""
 
 
 @dataclass
@@ -100,13 +161,13 @@ class SessionHeartbeatRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class SessionHeartbeatResultSuccess(ResultPayloadSuccess):
-    pass
+    """Session heartbeat successful. Session is active and responsive."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SessionHeartbeatResultFailure(ResultPayloadFailure):
-    pass
+    """Session heartbeat failed. Common causes: session inactive, network error, timeout."""
 
 
 @dataclass
@@ -125,6 +186,24 @@ class EngineHeartbeatRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class EngineHeartbeatResultSuccess(ResultPayloadSuccess):
+    """Engine heartbeat successful with comprehensive status information.
+
+    Args:
+        heartbeat_id: Unique identifier correlating with the request
+        engine_version: Current engine version string
+        engine_id: Unique engine identifier (None if not set)
+        session_id: Current session identifier (None if no session)
+        timestamp: Heartbeat timestamp
+        instance_type: Cloud instance type (None if not applicable)
+        instance_region: Cloud instance region (None if not applicable)
+        instance_provider: Cloud provider name (None if not applicable)
+        deployment_type: Type of deployment (None if not applicable)
+        current_workflow: Name of active workflow (None if none)
+        workflow_file_path: Path to workflow file (None if none)
+        has_active_flow: Whether there's an active flow running
+        engine_name: Human-readable engine name
+    """
+
     heartbeat_id: str
     engine_version: str
     engine_id: str | None
@@ -134,7 +213,6 @@ class EngineHeartbeatResultSuccess(ResultPayloadSuccess):
     instance_region: str | None
     instance_provider: str | None
     deployment_type: str | None
-    public_ip: str | None
     current_workflow: str | None
     workflow_file_path: str | None
     has_active_flow: bool
@@ -144,40 +222,87 @@ class EngineHeartbeatResultSuccess(ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class EngineHeartbeatResultFailure(ResultPayloadFailure):
+    """Engine heartbeat failed.
+
+    Args:
+        heartbeat_id: Unique identifier correlating with the request
+    """
+
     heartbeat_id: str
 
 
 @dataclass
 @PayloadRegistry.register
 class SetEngineNameRequest(RequestPayload):
+    """Set the human-readable engine name.
+
+    Use when: Customizing engine identification, setting up engine instances,
+    implementing engine management, branding engine instances.
+
+    Args:
+        engine_name: New name for the engine
+
+    Results: SetEngineNameResultSuccess (with name) | SetEngineNameResultFailure (validation error)
+    """
+
     engine_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class SetEngineNameResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Engine name set successfully.
+
+    Args:
+        engine_name: The name that was set for the engine
+    """
+
     engine_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class SetEngineNameResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Engine name setting failed.
+
+    Args:
+        error_message: Detailed error message describing the failure
+    """
+
     error_message: str
 
 
 @dataclass
 @PayloadRegistry.register
 class GetEngineNameRequest(RequestPayload):
-    pass
+    """Get the current engine name.
+
+    Use when: Displaying engine information, checking engine identity,
+    implementing engine management UIs, debugging engine issues.
+
+    Results: GetEngineNameResultSuccess (with name) | GetEngineNameResultFailure (retrieval error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetEngineNameResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Engine name retrieved successfully.
+
+    Args:
+        engine_name: Current engine name
+    """
+
     engine_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class GetEngineNameResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Engine name retrieval failed.
+
+    Args:
+        error_message: Detailed error message describing the failure
+    """
+
     error_message: str

griptape_nodes/retained_mode/events/arbitrary_python_events.py

@@ -15,16 +15,39 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class RunArbitraryPythonStringRequest(RequestPayload):
+    """Execute arbitrary Python code string.
+
+    Use when: Development/debugging, testing code snippets, prototyping,
+    educational purposes. WARNING: This is configurable behavior that can be disabled.
+
+    Args:
+        python_string: Python code string to execute
+
+    Results: RunArbitraryPythonStringResultSuccess (with output) | RunArbitraryPythonStringResultFailure (execution error)
+    """
+
     python_string: str
 
 
 @dataclass
 @PayloadRegistry.register
 class RunArbitraryPythonStringResultSuccess(ResultPayloadSuccess):
+    """Python code executed successfully.
+
+    Args:
+        python_output: String output from the executed Python code
+    """
+
     python_output: str
 
 
 @dataclass
 @PayloadRegistry.register
 class RunArbitraryPythonStringResultFailure(ResultPayloadFailure):
+    """Python code execution failed.
+
+    Args:
+        python_output: Error output from the failed Python code execution
+    """
+
     python_output: str

griptape_nodes/retained_mode/events/base_events.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 from abc import ABC, abstractmethod
 from dataclasses import asdict, dataclass, field, is_dataclass
-from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
 
 from griptape.artifacts import BaseArtifact
 from griptape.events import BaseEvent as GtBaseEvent
@@ -12,9 +12,6 @@ from griptape.structures import Structure
 from griptape.tools import BaseTool
 from pydantic import BaseModel, Field
 
-from griptape_nodes.retained_mode.utils.engine_identity import EngineIdentity
-from griptape_nodes.retained_mode.utils.session_persistence import SessionPersistence
-
 if TYPE_CHECKING:
     import builtins
 
@@ -104,7 +101,7 @@ class AppPayload(Payload):
 
 
 # Type variables for our generic payloads
-P = TypeVar("P", bound=Payload)
+P = TypeVar("P", bound=RequestPayload)
 R = TypeVar("R", bound=ResultPayload)
 E = TypeVar("E", bound=ExecutionPayload)
 A = TypeVar("A", bound=AppPayload)
@@ -113,32 +110,13 @@ A = TypeVar("A", bound=AppPayload)
 class BaseEvent(BaseModel, ABC):
     """Abstract base class for all events."""
 
-    # Keeping here instead of in GriptapeNodes to avoid circular import hell.
-    # TODO: https://github.com/griptape-ai/griptape-nodes/issues/848
-    _session_id: ClassVar[str | None] = None
+    # Instance fields for engine and session identification
     _engine_id: ClassVar[str | None] = None
+    _session_id: ClassVar[str | None] = None
 
-    # Instance variables with a default_factory that references the class variable
     engine_id: str | None = Field(default_factory=lambda: BaseEvent._engine_id)
     session_id: str | None = Field(default_factory=lambda: BaseEvent._session_id)
 
-    @classmethod
-    def initialize_engine_id(cls) -> None:
-        """Initialize the engine ID if not already set."""
-        if cls._engine_id is None:
-            persisted_engine_id = cls._engine_id = EngineIdentity.get_engine_id()
-            if persisted_engine_id:
-                cls._engine_id = persisted_engine_id
-
-    @classmethod
-    def initialize_session_id(cls) -> None:
-        """Initialize the session ID from persisted storage if available."""
-        if cls._session_id is None:
-            # Check if there's a persisted session ID
-            persisted_session_id = SessionPersistence.get_persisted_session_id()
-            if persisted_session_id:
-                cls._session_id = persisted_session_id
-
     # Custom JSON encoder for the payload
     class Config:
         """Pydantic configuration for the BaseEvent class."""
@@ -203,10 +181,12 @@ class BaseEvent(BaseModel, ABC):
         """
 
 
-class EventRequest(BaseEvent, Generic[P]):
+class EventRequest[P: Payload](BaseEvent):
     """Request event."""
 
     request: P
+    request_id: str | None = None
+    response_topic: str | None = None
 
     def __init__(self, **data) -> None:
         """Initialize an EventRequest, inferring the generic type if needed."""
@@ -262,14 +242,16 @@ class EventRequest(BaseEvent, Generic[P]):
             raise ValueError(msg)
 
         # Create the event instance with the payload
-        return cls(request=request_payload)
+        return cls(request=request_payload, **event_data)
 
 
-class EventResult(BaseEvent, Generic[P, R], ABC):
+class EventResult[P: RequestPayload, R: ResultPayload](BaseEvent, ABC):
     """Abstract base class for result events."""
 
     request: P
     result: R
+    request_id: str | None = None
+    response_topic: str | None = None
     retained_mode: str | None = None
 
     def __init__(self, **data) -> None:
@@ -447,7 +429,7 @@ def deserialize_event(json_data: str | dict | Any) -> BaseEvent:
 
 
 # EXECUTION EVENT BASE (this event type is used for the execution of a Griptape Nodes flow)
-class ExecutionEvent(BaseEvent, Generic[E]):
+class ExecutionEvent[E: ExecutionPayload](BaseEvent):
     payload: E
 
     def __init__(self, **data) -> None:
@@ -508,7 +490,7 @@ class ExecutionEvent(BaseEvent, Generic[E]):
 
 
 # Events sent as part of the lifecycle of the Griptape Nodes application.
-class AppEvent(BaseEvent, Generic[A]):
+class AppEvent[A: AppPayload](BaseEvent):
     payload: A
 
     def __init__(self, **data) -> None: