lfx-nightly 0.2.1.dev7__py3-none-any.whl → 0.3.0.dev3__py3-none-any.whl

lfx/custom/custom_component/component.py

@@ -1565,7 +1565,24 @@ class Component(CustomComponent):
         return has_chat_input(self.graph.get_vertex_neighbors(self._vertex))
 
     def _should_skip_message(self, message: Message) -> bool:
-        """Check if the message should be skipped based on vertex configuration and message type."""
+        """Check if the message should be skipped based on vertex configuration and message type.
+
+        When a message is skipped:
+        - It is NOT stored in the database
+        - It will NOT have an ID (message.get_id() will return None)
+        - It is still returned to the caller, but no events are sent to the frontend
+
+        Messages are skipped when:
+        - The component is not an input or output vertex
+        - The component is not connected to a Chat Output
+        - The message is not an ErrorMessage
+
+        This prevents intermediate components from cluttering the database with messages
+        that aren't meant to be displayed in the chat UI.
+
+        Returns:
+            bool: True if the message should be skipped, False otherwise
+        """
         return (
             self._vertex is not None
             and not (self._vertex.is_output or self._vertex.is_input)
@@ -1603,12 +1620,31 @@ class Component(CustomComponent):
     async def send_message(self, message: Message, id_: str | None = None, *, skip_db_update: bool = False):
         """Send a message with optional database update control.
 
+        This is the central method for sending messages in Langflow. It handles:
+        - Message storage in the database (unless skipped)
+        - Event emission to the frontend
+        - Streaming support
+        - Error handling and cleanup
+
+        Message ID Rules:
+        - Messages only have an ID after being stored in the database
+        - If _should_skip_message() returns True, the message is not stored and will not have an ID
+        - Always use message.get_id() or message.has_id() to safely check for ID existence
+        - Never access message.id directly without checking if it exists first
+
         Args:
             message: The message to send
-            id_: Optional message ID
+            id_: Optional message ID (used for event emission, not database storage)
             skip_db_update: If True, only update in-memory and send event, skip DB write.
                            Useful during streaming to avoid excessive DB round-trips.
-                           Note: This assumes the message already exists in the database with message.id set.
+                           Note: When skip_db_update=True, the message must already have an ID
+                           (i.e., it must have been stored previously).
+
+        Returns:
+            Message: The stored message (with ID if stored in database, without ID if skipped)
+
+        Raises:
+            ValueError: If skip_db_update=True but message doesn't have an ID
         """
         if self._should_skip_message(message):
             return message
@@ -1621,10 +1657,18 @@ class Component(CustomComponent):
 
         # If skip_db_update is True and message already has an ID, skip the DB write
         # This path is used during agent streaming to avoid excessive DB round-trips
-        if skip_db_update and message.id:
+        # When skip_db_update=True, we require the message to already have an ID
+        # because we're updating an existing message, not creating a new one
+        if skip_db_update:
+            if not message.has_id():
+                msg = (
+                    "skip_db_update=True requires the message to already have an ID. "
+                    "The message must have been stored in the database previously."
+                )
+                raise ValueError(msg)
             # Create a fresh Message instance for consistency with normal flow
             stored_message = await Message.create(**message.model_dump())
-            self._stored_message_id = stored_message.id
+            self._stored_message_id = stored_message.get_id()
             # Still send the event to update the client in real-time
             # Note: If this fails, we don't need DB cleanup since we didn't write to DB
             await self._send_message_event(stored_message, id_=id_)
@@ -1632,7 +1676,9 @@ class Component(CustomComponent):
             # Normal flow: store/update in database
             stored_message = await self._store_message(message)
 
-            self._stored_message_id = stored_message.id
+            # After _store_message, the message should always have an ID
+            # but we use get_id() for safety
+            self._stored_message_id = stored_message.get_id()
             try:
                 complete_message = ""
                 if (
@@ -1653,7 +1699,10 @@ class Component(CustomComponent):
                     await self._send_message_event(stored_message, id_=id_)
             except Exception:
                 # remove the message from the database
-                await delete_message(stored_message.id)
+                # Only delete if the message has an ID
+                message_id = stored_message.get_id()
+                if message_id:
+                    await delete_message(id_=message_id)
                 raise
         self.status = stored_message
         return stored_message
@@ -1699,7 +1748,7 @@ class Component(CustomComponent):
         return bool(
             hasattr(self, "_event_manager")
             and self._event_manager
-            and stored_message.id
+            and stored_message.has_id()
             and not isinstance(original_message.text, str)
         )
 
@@ -1726,14 +1775,20 @@ class Component(CustomComponent):
             msg = "The message must be an iterator or an async iterator."
             raise TypeError(msg)
 
+        # Get message ID safely - streaming requires an ID
+        message_id = message.get_id()
+        if not message_id:
+            msg = "Message must have an ID to stream. Messages only have IDs after being stored in the database."
+            raise ValueError(msg)
+
         if isinstance(iterator, AsyncIterator):
-            return await self._handle_async_iterator(iterator, message.id, message)
+            return await self._handle_async_iterator(iterator, message_id, message)
         try:
             complete_message = ""
             first_chunk = True
             for chunk in iterator:
                 complete_message = await self._process_chunk(
-                    chunk.content, complete_message, message.id, message, first_chunk=first_chunk
+                    chunk.content, complete_message, message_id, message, first_chunk=first_chunk
                 )
                 first_chunk = False
         except Exception as e:

lfx/events/observability/lifecycle_events.py

@@ -0,0 +1,111 @@
+import functools
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from ag_ui.encoder.encoder import EventEncoder
+
+from lfx.log.logger import logger
+
+AsyncMethod = Callable[..., Awaitable[Any]]
+
+encoder: EventEncoder = EventEncoder()
+
+
+def observable(observed_method: AsyncMethod) -> AsyncMethod:
+    """Decorator to make an async method observable by emitting lifecycle events.
+
+    Decorated classes are expected to implement specific methods to emit AGUI events:
+    - `before_callback_event(*args, **kwargs)`: Called before the decorated method executes.
+      It should return a dictionary representing the event payload.
+    - `after_callback_event(result, *args, **kwargs)`: Called after the decorated method
+      successfully completes. It should return a dictionary representing the event payload.
+      The `result` of the decorated method is passed as the first argument.
+    - `error_callback_event(exception, *args, **kwargs)`: (Optional) Called if the decorated
+      method raises an exception. It should return a dictionary representing the error event payload.
+      The `exception` is passed as the first argument.
+
+    If these methods are implemented, the decorator will call them to generate event payloads.
+    If an implementation is missing, the corresponding event publishing will be skipped without error.
+
+    Payloads returned by these methods can include custom metrics by placing them
+    under the 'langflow' key within the 'raw_events' dictionary.
+
+    Example:
+        class MyClass:
+            display_name = "My Observable Class"
+
+            def before_callback_event(self, *args, **kwargs):
+                return {"event_name": "my_method_started", "data": {"input_args": args}}
+
+            async def my_method(self, event_manager: EventManager, data: str):
+                # ... method logic ...
+                return "processed_data"
+
+            def after_callback_event(self, result, *args, **kwargs):
+                return {"event_name": "my_method_completed", "data": {"output": result}}
+
+            def error_callback_event(self, exception, *args, **kwargs):
+                return {"event_name": "my_method_failed", "error": str(exception)}
+
+        @observable
+        async def my_observable_method(self, event_manager: EventManager, data: str):
+            # ... method logic ...
+            pass
+    """
+
+    async def check_event_manager(self, **kwargs):
+        if "event_manager" not in kwargs or kwargs["event_manager"] is None:
+            await logger.awarning(
+                f"EventManager not available/provided, skipping observable event publishing "
+                f"from {self.__class__.__name__}"
+            )
+            return False
+        return True
+
+    async def before_callback(self, *args, **kwargs):
+        if not await check_event_manager(self, **kwargs):
+            return
+
+        if hasattr(self, "before_callback_event"):
+            event_payload = self.before_callback_event(*args, **kwargs)
+            event_payload = encoder.encode(event_payload)
+            # TODO: Publish event per request, would required context based queues
+        else:
+            await logger.awarning(
+                f"before_callback_event not implemented for {self.__class__.__name__}. Skipping event publishing."
+            )
+
+    async def after_callback(self, res: Any | None = None, *args, **kwargs):
+        if not await check_event_manager(self, **kwargs):
+            return
+        if hasattr(self, "after_callback_event"):
+            event_payload = self.after_callback_event(res, *args, **kwargs)
+            event_payload = encoder.encode(event_payload)
+            # TODO: Publish event per request, would required context based queues
+        else:
+            await logger.awarning(
+                f"after_callback_event not implemented for {self.__class__.__name__}. Skipping event publishing."
+            )
+
+    @functools.wraps(observed_method)
+    async def wrapper(self, *args, **kwargs):
+        await before_callback(self, *args, **kwargs)
+        result = None
+        try:
+            result = await observed_method(self, *args, **kwargs)
+            await after_callback(self, result, *args, **kwargs)
+        except Exception as e:
+            await logger.aerror(f"Exception in {self.__class__.__name__}: {e}")
+            if hasattr(self, "error_callback_event"):
+                try:
+                    event_payload = self.error_callback_event(e, *args, **kwargs)
+                    event_payload = encoder.encode(event_payload)
+                    # TODO: Publish event per request, would required context based queues
+                except Exception as callback_e:  # noqa: BLE001
+                    await logger.aerror(
+                        f"Exception during error_callback_event for {self.__class__.__name__}: {callback_e}"
+                    )
+            raise
+        return result
+
+    return wrapper

lfx/field_typing/__init__.py

@@ -1,63 +1,6 @@
 from typing import Any
 
-from .constants import (
-    AgentExecutor,
-    BaseChatMemory,
-    BaseChatModel,
-    BaseDocumentCompressor,
-    BaseLanguageModel,
-    BaseLLM,
-    BaseLoader,
-    BaseMemory,
-    BaseOutputParser,
-    BasePromptTemplate,
-    BaseRetriever,
-    Callable,
-    Chain,
-    ChatPromptTemplate,
-    Code,
-    Data,
-    Document,
-    Embeddings,
-    LanguageModel,
-    NestedDict,
-    Object,
-    PromptTemplate,
-    Retriever,
-    Text,
-    TextSplitter,
-    Tool,
-    VectorStore,
-)
-from .range_spec import RangeSpec
-
-
-def _import_input_class():
-    from lfx.template.field.base import Input
-
-    return Input
-
-
-def _import_output_class():
-    from lfx.template.field.base import Output
-
-    return Output
-
-
-def __getattr__(name: str) -> Any:
-    # This is to avoid circular imports
-    if name == "Input":
-        return _import_input_class()
-    if name == "Output":
-        return _import_output_class()
-    if name == "RangeSpec":
-        return RangeSpec
-    # The other names should work as if they were imported from constants
-    # Import the constants module langflow.field_typing.constants
-    from . import constants
-
-    return getattr(constants, name)
-
+# Lazy imports - nothing imported at module level except __all__
 
 __all__ = [
     "AgentExecutor",
@@ -78,9 +21,11 @@ __all__ = [
     "Data",
     "Document",
     "Embeddings",
+    "Input",
     "LanguageModel",
     "NestedDict",
     "Object",
+    "Output",
     "PromptTemplate",
     "RangeSpec",
     "Retriever",
@@ -89,3 +34,57 @@ __all__ = [
     "Tool",
     "VectorStore",
 ]
+
+# Names that come from constants module
+_CONSTANTS_NAMES = {
+    "AgentExecutor",
+    "BaseChatMemory",
+    "BaseChatModel",
+    "BaseDocumentCompressor",
+    "BaseLLM",
+    "BaseLanguageModel",
+    "BaseLoader",
+    "BaseMemory",
+    "BaseOutputParser",
+    "BasePromptTemplate",
+    "BaseRetriever",
+    "Callable",
+    "Chain",
+    "ChatPromptTemplate",
+    "Code",
+    "Data",
+    "Document",
+    "Embeddings",
+    "LanguageModel",
+    "NestedDict",
+    "Object",
+    "PromptTemplate",
+    "Retriever",
+    "Text",
+    "TextSplitter",
+    "Tool",
+    "VectorStore",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for all field typing constants."""
+    if name == "Input":
+        from lfx.template.field.base import Input
+
+        return Input
+    if name == "Output":
+        from lfx.template.field.base import Output
+
+        return Output
+    if name == "RangeSpec":
+        from .range_spec import RangeSpec
+
+        return RangeSpec
+    if name in _CONSTANTS_NAMES:
+        from . import constants
+
+        return getattr(constants, name)
+
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

lfx/graph/graph/base.py

@@ -15,6 +15,9 @@ from functools import partial
 from itertools import chain
 from typing import TYPE_CHECKING, Any, cast
 
+from ag_ui.core import RunFinishedEvent, RunStartedEvent
+
+from lfx.events.observability.lifecycle_events import observable
 from lfx.exceptions.component import ComponentBuildError
 from lfx.graph.edge.base import CycleEdge, Edge
 from lfx.graph.graph.constants import Finish, lazy_load_vertex_dict
@@ -728,6 +731,7 @@ class Graph:
                 raise ValueError(msg)
             vertex.update_raw_params(inputs, overwrite=True)
 
+    @observable
     async def _run(
         self,
         *,
@@ -1549,8 +1553,10 @@ class Graph:
                                 vertex.result.used_frozen_result = True
                         except Exception:  # noqa: BLE001
                             logger.debug("Error finalizing build", exc_info=True)
+                            vertex.built = False
                             should_build = True
                     except KeyError:
+                        vertex.built = False
                         should_build = True
 
             if should_build:
@@ -2132,6 +2138,17 @@ class Graph:
         """Get all vertex IDs in the graph."""
         return [vertex.id for vertex in self.vertices]
 
+    def get_terminal_nodes(self) -> list[str]:
+        """Returns vertex IDs that are terminal nodes (not source of any edge).
+
+        Terminal nodes are vertices that have no outgoing edges - they are not
+        listed as source_id in any of the graph's edges.
+
+        Returns:
+            list[str]: List of vertex IDs that are terminal nodes.
+        """
+        return [vertex.id for vertex in self.vertices if not self.successor_map.get(vertex.id, [])]
+
     def sort_vertices(
         self,
         stop_component_id: str | None = None,
@@ -2296,3 +2313,22 @@ class Graph:
             predecessors = [i.id for i in self.get_predecessors(vertex)]
             result |= {vertex_id: {"successors": sucessors, "predecessors": predecessors}}
         return result
+
+    def raw_event_metrics(self, optional_fields: dict | None = None) -> dict:
+        if optional_fields is None:
+            optional_fields = {}
+        import time
+
+        return {"timestamp": time.time(), **optional_fields}
+
+    def before_callback_event(self, *args, **kwargs) -> RunStartedEvent:  # noqa: ARG002
+        metrics = {}
+        if hasattr(self, "raw_event_metrics"):
+            metrics = self.raw_event_metrics({"total_components": len(self.vertices)})
+        return RunStartedEvent(run_id=self._run_id, thread_id=self.flow_id, raw_event=metrics)
+
+    def after_callback_event(self, result: Any = None, *args, **kwargs) -> RunFinishedEvent:  # noqa: ARG002
+        metrics = {}
+        if hasattr(self, "raw_event_metrics"):
+            metrics = self.raw_event_metrics({"total_components": len(self.vertices)})
+        return RunFinishedEvent(run_id=self._run_id, thread_id=self.flow_id, result=None, raw_event=metrics)

lfx/graph/utils.py

@@ -11,7 +11,7 @@ from lfx.schema.data import Data
 from lfx.schema.message import Message
 
 # Database imports removed - lfx should be lightweight
-from lfx.services.deps import get_db_service, get_settings_service
+from lfx.services.deps import get_settings_service
 
 if TYPE_CHECKING:
     from lfx.graph.vertex.base import Vertex
@@ -108,32 +108,65 @@ def _vertex_to_primitive_dict(target: Vertex) -> dict:
 async def log_transaction(
     flow_id: str | UUID,
     source: Vertex,
-    status,
-    target: Vertex | None = None,  # noqa: ARG001
-    error=None,  # noqa: ARG001
+    status: str,
+    target: Vertex | None = None,
+    error: str | Exception | None = None,
+    outputs: dict[str, Any] | None = None,
 ) -> None:
     """Asynchronously logs a transaction record for a vertex in a flow if transaction storage is enabled.
 
-    This is a lightweight implementation that only logs if database service is available.
+    Uses the pluggable TransactionService to log transactions. When running within langflow,
+    the concrete TransactionService implementation persists to the database.
+    When running standalone (lfx only), transactions are not persisted.
+
+    Args:
+        flow_id: The flow ID
+        source: The source vertex (component being executed)
+        status: Transaction status (success/error)
+        target: Optional target vertex (for data transfer logging)
+        error: Optional error information
+        outputs: Optional explicit outputs dict (component execution results)
     """
     try:
-        settings_service = get_settings_service()
-        if not settings_service or not getattr(settings_service.settings, "transactions_storage_enabled", False):
+        # Guard against null source
+        if source is None:
             return
 
-        db_service = get_db_service()
-        if db_service is None:
-            logger.debug("Database service not available, skipping transaction logging")
+        # Get the transaction service via dependency injection
+        from lfx.services.deps import get_transaction_service
+
+        transaction_service = get_transaction_service()
+
+        # If no transaction service is available or it's disabled, skip logging
+        if transaction_service is None or not transaction_service.is_enabled():
             return
 
+        # Resolve flow_id
         if not flow_id:
             if source.graph.flow_id:
                 flow_id = source.graph.flow_id
             else:
                 return
 
-        # Log basic transaction info - concrete implementation should be in langflow
-        logger.debug(f"Transaction logged: vertex={source.id}, flow={flow_id}, status={status}")
+        # Convert UUID to string for the service interface
+        flow_id_str = str(flow_id) if isinstance(flow_id, UUID) else flow_id
+
+        # Prepare inputs and outputs
+        inputs = _vertex_to_primitive_dict(source) if source else None
+        target_outputs = _vertex_to_primitive_dict(target) if target else None
+        transaction_outputs = outputs if outputs is not None else target_outputs
+
+        # Log transaction via the service
+        await transaction_service.log_transaction(
+            flow_id=flow_id_str,
+            vertex_id=source.id,
+            inputs=inputs,
+            outputs=transaction_outputs,
+            status=status,
+            target_id=target.id if target else None,
+            error=str(error) if error else None,
+        )
+
     except Exception as exc:  # noqa: BLE001
         logger.debug(f"Error logging transaction: {exc!s}")