uipath-langchain 0.0.133__py3-none-any.whl → 0.1.28__py3-none-any.whl

uipath_langchain/retrievers/context_grounding_retriever.py

@@ -1,24 +1,22 @@
-from typing import List, Optional
-
 from langchain_core.callbacks import (
     AsyncCallbackManagerForRetrieverRun,
     CallbackManagerForRetrieverRun,
 )
 from langchain_core.documents import Document
 from langchain_core.retrievers import BaseRetriever
-from uipath import UiPath
+from uipath.platform import UiPath
 
 
 class ContextGroundingRetriever(BaseRetriever):
     index_name: str
-    folder_path: Optional[str] = None
-    folder_key: Optional[str] = None
-    uipath_sdk: Optional[UiPath] = None
-    number_of_results: Optional[int] = 10
+    folder_path: str | None = None
+    folder_key: str | None = None
+    uipath_sdk: UiPath | None = None
+    number_of_results: int | None = 10
 
     def _get_relevant_documents(
         self, query: str, *, run_manager: CallbackManagerForRetrieverRun
-    ) -> List[Document]:
+    ) -> list[Document]:
         """Sync implementations for retriever calls context_grounding API to search the requested index."""
 
         sdk = self.uipath_sdk if self.uipath_sdk is not None else UiPath()
@@ -43,7 +41,7 @@ class ContextGroundingRetriever(BaseRetriever):
 
     async def _aget_relevant_documents(
         self, query: str, *, run_manager: AsyncCallbackManagerForRetrieverRun
-    ) -> List[Document]:
+    ) -> list[Document]:
         """Async implementations for retriever calls context_grounding API to search the requested index."""
 
         sdk = self.uipath_sdk if self.uipath_sdk is not None else UiPath()

uipath_langchain/runtime/__init__.py

@@ -0,0 +1,36 @@
+from uipath.runtime import (
+    UiPathRuntimeContext,
+    UiPathRuntimeFactoryProtocol,
+    UiPathRuntimeFactoryRegistry,
+)
+
+from uipath_langchain.runtime.factory import UiPathLangGraphRuntimeFactory
+from uipath_langchain.runtime.runtime import UiPathLangGraphRuntime
+from uipath_langchain.runtime.schema import (
+    get_entrypoints_schema,
+    get_graph_schema,
+)
+
+
+def register_runtime_factory() -> None:
+    """Register the LangGraph factory. Called automatically via entry point."""
+
+    def create_factory(
+        context: UiPathRuntimeContext | None = None,
+    ) -> UiPathRuntimeFactoryProtocol:
+        return UiPathLangGraphRuntimeFactory(
+            context=context if context else UiPathRuntimeContext(),
+        )
+
+    UiPathRuntimeFactoryRegistry.register("langgraph", create_factory, "langgraph.json")
+
+
+register_runtime_factory()
+
+__all__ = [
+    "register_runtime_factory",
+    "get_entrypoints_schema",
+    "get_graph_schema",
+    "UiPathLangGraphRuntimeFactory",
+    "UiPathLangGraphRuntime",
+]

uipath_langchain/runtime/_serialize.py

@@ -0,0 +1,46 @@
+from enum import Enum
+from typing import Any
+
+
+def serialize_output(output: Any) -> Any:
+    """
+    Recursively serialize an output object.
+
+    Args:
+        output: The object to serialize
+
+    Returns:
+        Dict[str, Any]: Serialized output as dictionary
+    """
+    if output is None:
+        return {}
+
+    # Handle Pydantic models
+    if hasattr(output, "model_dump"):
+        return serialize_output(output.model_dump(by_alias=True))
+    elif hasattr(output, "dict"):
+        return serialize_output(output.dict())
+    elif hasattr(output, "to_dict"):
+        return serialize_output(output.to_dict())
+
+    # Handle dictionaries
+    elif isinstance(output, dict):
+        return {k: serialize_output(v) for k, v in output.items()}
+
+    # Handle lists
+    elif isinstance(output, list):
+        return [serialize_output(item) for item in output]
+
+    # Handle other iterables (convert to dict first)
+    elif hasattr(output, "__iter__") and not isinstance(output, (str, bytes)):
+        try:
+            return serialize_output(dict(output))
+        except (TypeError, ValueError):
+            return output
+
+    # Handle Enums
+    elif isinstance(output, Enum):
+        return output.value
+
+    # Return primitive types as is
+    return output

uipath_langchain/runtime/config.py

@@ -0,0 +1,61 @@
+"""Simple loader for langgraph.json configuration."""
+
+import json
+import os
+
+
+class LangGraphConfig:
+    """Simple loader for langgraph.json configuration."""
+
+    def __init__(self, config_path: str = "langgraph.json"):
+        """
+        Initialize configuration loader.
+
+        Args:
+            config_path: Path to langgraph.json file
+        """
+        self.config_path = config_path
+        self._graphs: dict[str, str] | None = None
+
+    @property
+    def exists(self) -> bool:
+        """Check if langgraph.json exists."""
+        return os.path.exists(self.config_path)
+
+    @property
+    def graphs(self) -> dict[str, str]:
+        """
+        Get graph name -> path mapping from config.
+
+        Returns:
+            Dictionary mapping graph names to file paths (e.g., {"agent": "agent.py:graph"})
+        """
+        if self._graphs is None:
+            self._graphs = self._load_graphs()
+        return self._graphs
+
+    def _load_graphs(self) -> dict[str, str]:
+        """Load graph definitions from langgraph.json."""
+        if not self.exists:
+            raise FileNotFoundError(f"Config file not found: {self.config_path}")
+
+        try:
+            with open(self.config_path, "r") as f:
+                config = json.load(f)
+
+            if "graphs" not in config:
+                raise ValueError("Missing required 'graphs' field in langgraph.json")
+
+            graphs = config["graphs"]
+            if not isinstance(graphs, dict):
+                raise ValueError("'graphs' must be a dictionary")
+
+            return graphs
+
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in {self.config_path}: {e}") from e
+
+    @property
+    def entrypoints(self) -> list[str]:
+        """Get list of available graph entrypoints."""
+        return list(self.graphs.keys())

uipath_langchain/runtime/errors.py

@@ -0,0 +1,43 @@
+from enum import Enum
+from typing import Union
+
+from uipath.runtime.errors import (
+    UiPathBaseRuntimeError,
+    UiPathErrorCategory,
+    UiPathErrorCode,
+)
+
+
+class LangGraphErrorCode(Enum):
+    CONFIG_MISSING = "CONFIG_MISSING"
+    CONFIG_INVALID = "CONFIG_INVALID"
+
+    GRAPH_NOT_FOUND = "GRAPH_NOT_FOUND"
+    GRAPH_IMPORT_ERROR = "GRAPH_IMPORT_ERROR"
+    GRAPH_TYPE_ERROR = "GRAPH_TYPE_ERROR"
+    GRAPH_VALUE_ERROR = "GRAPH_VALUE_ERROR"
+    GRAPH_LOAD_ERROR = "GRAPH_LOAD_ERROR"
+    GRAPH_INVALID_UPDATE = "GRAPH_INVALID_UPDATE"
+    GRAPH_EMPTY_INPUT = "GRAPH_EMPTY_INPUT"
+
+    DB_QUERY_FAILED = "DB_QUERY_FAILED"
+    DB_TABLE_CREATION_FAILED = "DB_TABLE_CREATION_FAILED"
+    HITL_EVENT_CREATION_FAILED = "HITL_EVENT_CREATION_FAILED"
+    DB_INSERT_FAILED = "DB_INSERT_FAILED"
+    LICENSE_NOT_AVAILABLE = "LICENSE_NOT_AVAILABLE"
+
+
+class LangGraphRuntimeError(UiPathBaseRuntimeError):
+    """Custom exception for LangGraph runtime errors with structured error information."""
+
+    def __init__(
+        self,
+        code: Union[LangGraphErrorCode, UiPathErrorCode],
+        title: str,
+        detail: str,
+        category: UiPathErrorCategory = UiPathErrorCategory.UNKNOWN,
+        status: int | None = None,
+    ):
+        super().__init__(
+            code.value, title, detail, category, status, prefix="LANGGRAPH"
+        )

uipath_langchain/runtime/factory.py

@@ -0,0 +1,315 @@
+import asyncio
+import os
+from typing import Any, AsyncContextManager
+
+from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+from langgraph.graph.state import CompiledStateGraph, StateGraph
+from openinference.instrumentation.langchain import (
+    LangChainInstrumentor,
+    get_ancestor_spans,
+    get_current_span,
+)
+from uipath.core.tracing import UiPathSpanUtils, UiPathTraceManager
+from uipath.platform.resume_triggers import (
+    UiPathResumeTriggerHandler,
+)
+from uipath.runtime import (
+    UiPathResumableRuntime,
+    UiPathRuntimeContext,
+    UiPathRuntimeProtocol,
+)
+from uipath.runtime.errors import UiPathErrorCategory
+
+from uipath_langchain._tracing import _instrument_traceable_attributes
+from uipath_langchain.runtime.config import LangGraphConfig
+from uipath_langchain.runtime.errors import LangGraphErrorCode, LangGraphRuntimeError
+from uipath_langchain.runtime.graph import LangGraphLoader
+from uipath_langchain.runtime.runtime import UiPathLangGraphRuntime
+from uipath_langchain.runtime.storage import SqliteResumableStorage
+
+
+class UiPathLangGraphRuntimeFactory:
+    """Factory for creating LangGraph runtimes from langgraph.json configuration."""
+
+    def __init__(
+        self,
+        context: UiPathRuntimeContext,
+    ):
+        """
+        Initialize the factory.
+
+        Args:
+            context: UiPathRuntimeContext to use for runtime creation
+        """
+        self.context = context
+        self._config: LangGraphConfig | None = None
+        self._memory: AsyncSqliteSaver | None = None
+        self._memory_cm: AsyncContextManager[AsyncSqliteSaver] | None = None
+        self._memory_lock = asyncio.Lock()
+
+        self._graph_cache: dict[str, CompiledStateGraph[Any, Any, Any, Any]] = {}
+        self._graph_loaders: dict[str, LangGraphLoader] = {}
+        self._graph_lock = asyncio.Lock()
+
+        self._setup_instrumentation(self.context.trace_manager)
+
+    def _setup_instrumentation(self, trace_manager: UiPathTraceManager | None) -> None:
+        """Setup tracing and instrumentation."""
+        _instrument_traceable_attributes()
+        LangChainInstrumentor().instrument()
+        UiPathSpanUtils.register_current_span_provider(get_current_span)
+        UiPathSpanUtils.register_current_span_ancestors_provider(get_ancestor_spans)
+
+    def _get_connection_string(self) -> str:
+        """Get the database connection string."""
+        if self.context.runtime_dir and self.context.state_file:
+            path = os.path.join(self.context.runtime_dir, self.context.state_file)
+            if not self.context.resume and self.context.job_id is None:
+                # If not resuming and no job id, delete the previous state file
+                if os.path.exists(path):
+                    os.remove(path)
+            os.makedirs(self.context.runtime_dir, exist_ok=True)
+            return path
+
+        default_path = os.path.join("__uipath", "state.db")
+        os.makedirs(os.path.dirname(default_path), exist_ok=True)
+        return default_path
+
+    async def _get_memory(self) -> AsyncSqliteSaver:
+        """Get or create the shared memory instance."""
+        async with self._memory_lock:
+            if self._memory is None:
+                connection_string = self._get_connection_string()
+                self._memory_cm = AsyncSqliteSaver.from_conn_string(connection_string)
+                self._memory = await self._memory_cm.__aenter__()
+                await self._memory.setup()
+        return self._memory
+
+    def _load_config(self) -> LangGraphConfig:
+        """Load langgraph.json configuration."""
+        if self._config is None:
+            self._config = LangGraphConfig()
+        return self._config
+
+    async def _load_graph(
+        self, entrypoint: str
+    ) -> StateGraph[Any, Any, Any] | CompiledStateGraph[Any, Any, Any, Any]:
+        """
+        Load a graph for the given entrypoint.
+
+        Args:
+            entrypoint: Name of the graph to load
+
+        Returns:
+            The loaded StateGraph or CompiledStateGraph
+
+        Raises:
+            LangGraphRuntimeError: If graph cannot be loaded
+        """
+        config = self._load_config()
+        if not config.exists:
+            raise LangGraphRuntimeError(
+                LangGraphErrorCode.CONFIG_MISSING,
+                "Invalid configuration",
+                "Failed to load configuration",
+                UiPathErrorCategory.DEPLOYMENT,
+            )
+
+        if entrypoint not in config.graphs:
+            available = ", ".join(config.entrypoints)
+            raise LangGraphRuntimeError(
+                LangGraphErrorCode.GRAPH_NOT_FOUND,
+                "Graph not found",
+                f"Graph '{entrypoint}' not found. Available: {available}",
+                UiPathErrorCategory.DEPLOYMENT,
+            )
+
+        path = config.graphs[entrypoint]
+        graph_loader = LangGraphLoader.from_path_string(entrypoint, path)
+
+        self._graph_loaders[entrypoint] = graph_loader
+
+        try:
+            return await graph_loader.load()
+
+        except ImportError as e:
+            raise LangGraphRuntimeError(
+                LangGraphErrorCode.GRAPH_IMPORT_ERROR,
+                "Graph import failed",
+                f"Failed to import graph '{entrypoint}': {str(e)}",
+                UiPathErrorCategory.USER,
+            ) from e
+        except TypeError as e:
+            raise LangGraphRuntimeError(
+                LangGraphErrorCode.GRAPH_TYPE_ERROR,
+                "Invalid graph type",
+                f"Graph '{entrypoint}' is not a valid StateGraph or CompiledStateGraph: {str(e)}",
+                UiPathErrorCategory.USER,
+            ) from e
+        except ValueError as e:
+            raise LangGraphRuntimeError(
+                LangGraphErrorCode.GRAPH_VALUE_ERROR,
+                "Invalid graph value",
+                f"Invalid value in graph '{entrypoint}': {str(e)}",
+                UiPathErrorCategory.USER,
+            ) from e
+        except Exception as e:
+            raise LangGraphRuntimeError(
+                LangGraphErrorCode.GRAPH_LOAD_ERROR,
+                "Failed to load graph",
+                f"Unexpected error loading graph '{entrypoint}': {str(e)}",
+                UiPathErrorCategory.USER,
+            ) from e
+
+    async def _compile_graph(
+        self,
+        graph: StateGraph[Any, Any, Any] | CompiledStateGraph[Any, Any, Any, Any],
+        memory: AsyncSqliteSaver,
+    ) -> CompiledStateGraph[Any, Any, Any, Any]:
+        """
+        Compile a graph with the given memory/checkpointer.
+
+        Args:
+            graph: The graph to compile (StateGraph or already compiled)
+            memory: Checkpointer to use for compiled graph
+
+        Returns:
+            The compiled StateGraph
+        """
+        builder = graph.builder if isinstance(graph, CompiledStateGraph) else graph
+
+        return builder.compile(checkpointer=memory)
+
+    async def _resolve_and_compile_graph(
+        self, entrypoint: str, memory: AsyncSqliteSaver
+    ) -> CompiledStateGraph[Any, Any, Any, Any]:
+        """
+        Resolve a graph from configuration and compile it.
+        Results are cached for reuse across multiple runtime instances.
+
+        Args:
+            entrypoint: Name of the graph to resolve
+            memory: Checkpointer to use for compiled graph
+
+        Returns:
+            The compiled StateGraph ready for execution
+
+        Raises:
+            LangGraphRuntimeError: If resolution or compilation fails
+        """
+        async with self._graph_lock:
+            if entrypoint in self._graph_cache:
+                return self._graph_cache[entrypoint]
+
+            loaded_graph = await self._load_graph(entrypoint)
+
+            compiled_graph = await self._compile_graph(loaded_graph, memory)
+
+            self._graph_cache[entrypoint] = compiled_graph
+
+            return compiled_graph
+
+    def discover_entrypoints(self) -> list[str]:
+        """
+        Discover all graph entrypoints.
+
+        Returns:
+            List of graph names that can be used as entrypoints
+        """
+        config = self._load_config()
+        if not config.exists:
+            return []
+        return config.entrypoints
+
+    async def discover_runtimes(self) -> list[UiPathRuntimeProtocol]:
+        """
+        Discover runtime instances for all entrypoints.
+
+        Returns:
+            List of LangGraphRuntime instances, one per entrypoint
+        """
+        entrypoints = self.discover_entrypoints()
+        memory = await self._get_memory()
+
+        runtimes: list[UiPathRuntimeProtocol] = []
+        for entrypoint in entrypoints:
+            compiled_graph = await self._resolve_and_compile_graph(entrypoint, memory)
+
+            runtime = await self._create_runtime_instance(
+                compiled_graph=compiled_graph,
+                runtime_id=entrypoint,
+                entrypoint=entrypoint,
+            )
+            runtimes.append(runtime)
+
+        return runtimes
+
+    async def _create_runtime_instance(
+        self,
+        compiled_graph: CompiledStateGraph[Any, Any, Any, Any],
+        runtime_id: str,
+        entrypoint: str,
+    ) -> UiPathRuntimeProtocol:
+        """
+        Create a runtime instance from a compiled graph.
+
+        Args:
+            compiled_graph: The compiled graph
+            runtime_id: Unique identifier for the runtime instance
+            entrypoint: Graph entrypoint name
+
+        Returns:
+            Configured runtime instance
+        """
+        base_runtime = UiPathLangGraphRuntime(
+            graph=compiled_graph,
+            runtime_id=runtime_id,
+            entrypoint=entrypoint,
+        )
+
+        memory = await self._get_memory()
+        storage = SqliteResumableStorage(memory)
+        trigger_manager = UiPathResumeTriggerHandler()
+
+        return UiPathResumableRuntime(
+            delegate=base_runtime,
+            storage=storage,
+            trigger_manager=trigger_manager,
+        )
+
+    async def new_runtime(
+        self, entrypoint: str, runtime_id: str
+    ) -> UiPathRuntimeProtocol:
+        """
+        Create a new LangGraph runtime instance.
+
+        Args:
+            entrypoint: Graph name from langgraph.json
+            runtime_id: Unique identifier for the runtime instance
+
+        Returns:
+            Configured runtime instance with compiled graph
+        """
+        # Get shared memory instance
+        memory = await self._get_memory()
+
+        compiled_graph = await self._resolve_and_compile_graph(entrypoint, memory)
+
+        return await self._create_runtime_instance(
+            compiled_graph=compiled_graph,
+            runtime_id=runtime_id,
+            entrypoint=entrypoint,
+        )
+
+    async def dispose(self) -> None:
+        """Cleanup factory resources."""
+        for loader in self._graph_loaders.values():
+            await loader.cleanup()
+
+        self._graph_loaders.clear()
+        self._graph_cache.clear()
+
+        if self._memory_cm is not None:
+            await self._memory_cm.__aexit__(None, None, None)
+            self._memory_cm = None
+            self._memory = None