langchain-arcade 1.0.0__tar.gz

langchain_arcade-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, Arcade AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langchain_arcade-1.0.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.1
+Name: langchain-arcade
+Version: 1.0.0
+Summary: An integration package connecting Arcade and LangChain/LangGraph
+Home-page: https://github.com/arcadeai/arcade-ai/tree/main/contrib/langchain
+License: MIT
+Author: Arcade AI
+Author-email: dev@arcade-ai.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: arcadepy (>=1.0.0,<2.0.0)
+Requires-Dist: langgraph (>=0.2.67,<0.3.0)
+Project-URL: Repository, https://github.com/arcadeai/arcade-ai/tree/main/contrib/langchain
+Description-Content-Type: text/markdown
+
+<h3 align="center">
+  <a name="readme-top"></a>
+  <img
+    src="https://docs.arcade-ai.com/images/logo/arcade-ai-logo.png"
+  >
+</h3>
+<div align="center">
+  <h3>LangChain Integration</h3>
+    <a href="https://github.com/arcadeai/arcade-ai/blob/main/LICENSE">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
+</a>
+    <a href="https://pepy.tech/project/langchain-arcade">
+  <img src="https://static.pepy.tech/badge/langchain-arcade" alt="Downloads">
+</a>
+
+</div>
+
+<p align="center">
+    <a href="https://docs.arcade-ai.com" target="_blank">Docs</a> •
+    <a href="https://docs.arcade-ai.com/integrations" target="_blank">Integrations</a> •
+    <a href="https://github.com/ArcadeAI/cookbook" target="_blank">Cookbook</a> •
+    <a href="https://github.com/ArcadeAI/arcade-py" target="_blank">Python Client</a> •
+    <a href="https://github.com/ArcadeAI/arcade-js" target="_blank">JavaScript Client</a>
+</p>
+
+## Overview
+
+`langchain-arcade` allows you to use Arcade AI tools in your LangChain and LangGraph applications.
+
+## Installation
+
+```bash
+pip install langchain-arcade
+```
+
+## Usage
+
+See the [examples](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/langchain) for usage examples
+

langchain_arcade-1.0.0/README.md

@@ -0,0 +1,38 @@
+<h3 align="center">
+  <a name="readme-top"></a>
+  <img
+    src="https://docs.arcade-ai.com/images/logo/arcade-ai-logo.png"
+  >
+</h3>
+<div align="center">
+  <h3>LangChain Integration</h3>
+    <a href="https://github.com/arcadeai/arcade-ai/blob/main/LICENSE">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License">
+</a>
+    <a href="https://pepy.tech/project/langchain-arcade">
+  <img src="https://static.pepy.tech/badge/langchain-arcade" alt="Downloads">
+</a>
+
+</div>
+
+<p align="center">
+    <a href="https://docs.arcade-ai.com" target="_blank">Docs</a> •
+    <a href="https://docs.arcade-ai.com/integrations" target="_blank">Integrations</a> •
+    <a href="https://github.com/ArcadeAI/cookbook" target="_blank">Cookbook</a> •
+    <a href="https://github.com/ArcadeAI/arcade-py" target="_blank">Python Client</a> •
+    <a href="https://github.com/ArcadeAI/arcade-js" target="_blank">JavaScript Client</a>
+</p>
+
+## Overview
+
+`langchain-arcade` allows you to use Arcade AI tools in your LangChain and LangGraph applications.
+
+## Installation
+
+```bash
+pip install langchain-arcade
+```
+
+## Usage
+
+See the [examples](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/langchain) for usage examples

langchain_arcade-1.0.0/langchain_arcade/__init__.py

@@ -0,0 +1,3 @@
+from .manager import ArcadeToolManager
+
+__all__ = ["ArcadeToolManager"]

langchain_arcade-1.0.0/langchain_arcade/_utilities.py

@@ -0,0 +1,179 @@
+from typing import Any, Callable
+
+from arcadepy import NOT_GIVEN, Arcade
+from arcadepy.types import ToolDefinition
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field, create_model
+
+# Check if LangGraph is enabled
+LANGGRAPH_ENABLED = True
+try:
+    from langgraph.errors import NodeInterrupt
+except ImportError:
+    LANGGRAPH_ENABLED = False
+
+# Mapping of Arcade value types to Python types
+TYPE_MAPPING = {
+    "string": str,
+    "number": float,
+    "integer": int,
+    "boolean": bool,
+    "array": list,
+    "json": dict,
+}
+
+
+def get_python_type(val_type: str) -> Any:
+    """Map Arcade value types to Python types.
+
+    Args:
+        val_type: The value type as a string.
+
+    Returns:
+        Corresponding Python type.
+    """
+    _type = TYPE_MAPPING.get(val_type)
+    if _type is None:
+        raise ValueError(f"Invalid value type: {val_type}")
+    return _type
+
+
+def tool_definition_to_pydantic_model(tool_def: ToolDefinition) -> type[BaseModel]:
+    """Convert a ToolDefinition's inputs into a Pydantic BaseModel.
+
+    Args:
+        tool_def: The ToolDefinition object to convert.
+
+    Returns:
+        A Pydantic BaseModel class representing the tool's input schema.
+    """
+    try:
+        fields: dict[str, Any] = {}
+        for param in tool_def.input.parameters or []:
+            param_type = get_python_type(param.value_schema.val_type)
+            if param_type == list and param.value_schema.inner_val_type:  # noqa: E721
+                inner_type: type[Any] = get_python_type(param.value_schema.inner_val_type)
+                param_type = list[inner_type]  # type: ignore[valid-type]
+            param_description = param.description or "No description provided."
+            default = ... if param.required else None
+            fields[param.name] = (
+                param_type,
+                Field(default=default, description=param_description),
+            )
+        return create_model(f"{tool_def.name}Args", **fields)
+    except ValueError as e:
+        raise ValueError(
+            f"Error converting {tool_def.name} parameters into pydantic model for langchain: {e}"
+        )
+
+
+def create_tool_function(
+    client: Arcade,
+    tool_name: str,
+    tool_def: ToolDefinition,
+    args_schema: type[BaseModel],
+    langgraph: bool = False,
+) -> Callable:
+    """Create a callable function to execute an Arcade tool.
+
+    Args:
+        client: The Arcade client instance.
+        tool_name: The name of the tool to wrap.
+        tool_def: The ToolDefinition of the tool to wrap.
+        args_schema: The Pydantic model representing the tool's arguments.
+        langgraph: Whether to enable LangGraph-specific behavior.
+
+    Returns:
+        A callable function that executes the tool.
+    """
+    if langgraph and not LANGGRAPH_ENABLED:
+        raise ImportError("LangGraph is not installed. Please install it to use this feature.")
+
+    requires_authorization = (
+        tool_def.requirements is not None and tool_def.requirements.authorization is not None
+    )
+
+    def tool_function(config: RunnableConfig, **kwargs: Any) -> Any:
+        """Execute the Arcade tool with the given parameters.
+
+        Args:
+            config: RunnableConfig containing execution context.
+            **kwargs: Tool input arguments.
+
+        Returns:
+            The output from the tool execution.
+        """
+        user_id = config.get("configurable", {}).get("user_id") if config else None
+
+        if requires_authorization:
+            if user_id is None:
+                error_message = f"user_id is required to run {tool_name}"
+                if langgraph:
+                    raise NodeInterrupt(error_message)
+                return {"error": error_message}
+
+            # Authorize the user for the tool
+            auth_response = client.tools.authorize(tool_name=tool_name, user_id=user_id)
+            if auth_response.status != "completed":
+                auth_message = f"Please use the following link to authorize: {auth_response.url}"
+                if langgraph:
+                    raise NodeInterrupt(auth_message)
+                return {"error": auth_message}
+
+        # Execute the tool with provided inputs
+        execute_response = client.tools.execute(
+            tool_name=tool_name,
+            input=kwargs,
+            user_id=user_id if user_id is not None else NOT_GIVEN,
+        )
+
+        if execute_response.success:
+            return execute_response.output.value  # type: ignore[union-attr]
+        error_message = str(execute_response.output.error)  # type: ignore[union-attr]
+        if langgraph:
+            raise NodeInterrupt(error_message)
+        return {"error": error_message}
+
+    return tool_function
+
+
+def wrap_arcade_tool(
+    client: Arcade,
+    tool_name: str,
+    tool_def: ToolDefinition,
+    langgraph: bool = False,
+) -> StructuredTool:
+    """Wrap an Arcade `ToolDefinition` as a LangChain `StructuredTool`.
+
+    Args:
+        client: The Arcade client instance.
+        tool_name: The name of the tool to wrap.
+        tool_def: The ToolDefinition object to wrap.
+        langgraph: Whether to enable LangGraph-specific behavior.
+
+    Returns:
+        A StructuredTool instance representing the Arcade tool.
+    """
+    description = tool_def.description or "No description provided."
+
+    # Create a Pydantic model for the tool's input arguments
+    args_schema = tool_definition_to_pydantic_model(tool_def)
+
+    # Create the action function
+    action_func = create_tool_function(
+        client=client,
+        tool_name=tool_name,
+        tool_def=tool_def,
+        args_schema=args_schema,
+        langgraph=langgraph,
+    )
+
+    # Create the StructuredTool instance
+    return StructuredTool.from_function(
+        func=action_func,
+        name=tool_name,
+        description=description,
+        args_schema=args_schema,
+        inject_kwargs={"user_id"},
+    )

langchain_arcade-1.0.0/langchain_arcade/manager.py

@@ -0,0 +1,219 @@
+import os
+from collections.abc import Iterator
+from typing import Any, Optional
+
+from arcadepy import Arcade
+from arcadepy.types import ToolDefinition
+from arcadepy.types.shared import AuthorizationResponse
+from langchain_core.tools import StructuredTool
+
+from langchain_arcade._utilities import (
+    wrap_arcade_tool,
+)
+
+
+class ArcadeToolManager:
+    """
+    Arcade tool manager for LangChain framework.
+
+    This class wraps Arcade tools as LangChain `StructuredTool`
+    objects for integration.
+    """
+
+    def __init__(
+        self,
+        client: Optional[Arcade] = None,
+        **kwargs: dict[str, Any],
+    ) -> None:
+        """Initialize the ArcadeToolManager.
+
+        Example:
+            >>> manager = ArcadeToolManager(api_key="...")
+            >>>
+            >>> # retrieve a specific tool as a langchain tool
+            >>> manager.get_tools(tools=["Search.SearchGoogle"])
+            >>>
+            >>> # retrieve all tools in a toolkit as langchain tools
+            >>> manager.get_tools(toolkits=["Search"])
+            >>>
+            >>> # clear and initialize new tools in the manager
+            >>> manager.init_tools(tools=["Search.SearchGoogle"], toolkits=["Search"])
+
+        Args:
+            client: Optional Arcade client instance.
+            **kwargs: Additional keyword arguments to pass to the Arcade client.
+        """
+        if not client:
+            api_key = kwargs.get("api_key", os.getenv("ARCADE_API_KEY"))
+            base_url = kwargs.get("base_url", os.getenv("ARCADE_BASE_URL"))
+            arcade_kwargs = {"api_key": api_key, **kwargs}
+            if base_url:
+                arcade_kwargs["base_url"] = base_url
+
+            client = Arcade(**arcade_kwargs)  # type: ignore[arg-type]
+        self.client = client
+        self._tools: dict[str, ToolDefinition] = {}
+
+    @property
+    def tools(self) -> list[str]:
+        return list(self._tools.keys())
+
+    def __iter__(self) -> Iterator[tuple[str, ToolDefinition]]:
+        yield from self._tools.items()
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __getitem__(self, tool_name: str) -> ToolDefinition:
+        return self._tools[tool_name]
+
+    def init_tools(
+        self,
+        tools: Optional[list[str]] = None,
+        toolkits: Optional[list[str]] = None,
+    ) -> None:
+        """Initialize the tools in the manager.
+
+        This will clear any existing tools in the manager.
+
+        Example:
+            >>> manager = ArcadeToolManager(api_key="...")
+            >>> manager.init_tools(tools=["Search.SearchGoogle"])
+            >>> manager.get_tools()
+
+        Args:
+            tools: Optional list of tool names to include.
+            toolkits: Optional list of toolkits to include.
+        """
+        self._tools = self._retrieve_tool_definitions(tools, toolkits)
+
+    def get_tools(
+        self,
+        tools: Optional[list[str]] = None,
+        toolkits: Optional[list[str]] = None,
+        langgraph: bool = True,
+    ) -> list[StructuredTool]:
+        """Return the tools in the manager as LangChain StructuredTool objects.
+
+        Note: if tools/toolkits are provided, the manager will update it's
+        internal tools using a dictionary update by tool name.
+
+        If langgraph is True, the tools will be wrapped with LangGraph-specific
+        behavior such as NodeInterrupts for auth.
+        Note: Changed in 1.0.0 to default to True.
+
+        Example:
+            >>> manager = ArcadeToolManager(api_key="...")
+            >>>
+            >>> # retrieve a specific tool as a langchain tool
+            >>> manager.get_tools(tools=["Search.SearchGoogle"])
+
+        Args:
+            tools: Optional list of tool names to include.
+            toolkits: Optional list of toolkits to include.
+            langgraph: Whether to use LangGraph-specific behavior
+                such as NodeInterrupts for auth.
+
+        Returns:
+            List of StructuredTool instances.
+        """
+        # TODO account for versioning
+        if tools or toolkits:
+            new_tools = self._retrieve_tool_definitions(tools, toolkits)
+            self._tools.update(new_tools)
+        elif len(self) == 0:
+            self.init_tools()
+
+        langchain_tools: list[StructuredTool] = []
+        for tool_name, definition in self:
+            lc_tool = wrap_arcade_tool(self.client, tool_name, definition, langgraph)
+            langchain_tools.append(lc_tool)
+        return langchain_tools
+
+    def authorize(self, tool_name: str, user_id: str) -> AuthorizationResponse:
+        """Authorize a user for a tool.
+
+        Example:
+            >>> manager = ArcadeToolManager(api_key="...")
+            >>> manager.authorize("X.PostTweet", "user_123")
+
+        Args:
+            tool_name: The name of the tool to authorize.
+            user_id: The user ID to authorize.
+
+        Returns:
+            AuthorizationResponse
+        """
+        return self.client.tools.authorize(tool_name=tool_name, user_id=user_id)
+
+    def is_authorized(self, authorization_id: str) -> bool:
+        """Check if a tool authorization is complete.
+
+        Example:
+            >>> manager = ArcadeToolManager(api_key="...")
+            >>> manager.init_tools(toolkits=["Search"])
+            >>> manager.is_authorized("auth_123")
+        """
+        return self.client.auth.status(id=authorization_id).status == "completed"
+
+    def wait_for_auth(self, authorization_id: str) -> AuthorizationResponse:
+        """Wait for a tool authorization to complete.
+
+        Example:
+            >>> manager = ArcadeToolManager(api_key="...")
+            >>> manager.init_tools(toolkits=["Google.ListEmails"])
+            >>> response = manager.authorize("Google.ListEmails", "user_123")
+            >>> manager.wait_for_auth(response)
+            >>> # or
+            >>> manager.wait_for_auth(response.id)
+        """
+        return self.client.auth.wait_for_completion(authorization_id)
+
+    def requires_auth(self, tool_name: str) -> bool:
+        """Check if a tool requires authorization."""
+
+        tool_def = self._get_tool_definition(tool_name)
+        if tool_def.requirements is None:
+            return False
+        return tool_def.requirements.authorization is not None
+
+    def _get_tool_definition(self, tool_name: str) -> ToolDefinition:
+        try:
+            return self._tools[tool_name]
+        except KeyError:
+            raise ValueError(f"Tool '{tool_name}' not found in this ArcadeToolManager instance")
+
+    def _retrieve_tool_definitions(
+        self, tools: Optional[list[str]] = None, toolkits: Optional[list[str]] = None
+    ) -> dict[str, ToolDefinition]:
+        """Retrieve tool definitions from the Arcade client, accounting for pagination."""
+        all_tools: list[ToolDefinition] = []
+
+        # First, gather single tools if the user specifically requested them.
+        if tools:
+            for tool_id in tools:
+                # ToolsResource.get(...) returns a single ToolDefinition.
+                single_tool = self.client.tools.get(name=tool_id)
+                all_tools.append(single_tool)
+
+        # Next, gather tool definitions from any requested toolkits.
+        if toolkits:
+            for tk in toolkits:
+                # tools.list(...) returns a paginated response (SyncOffsetPage),
+                # so we iterate over its items to accumulate tool definitions.
+                paginated_tools = self.client.tools.list(toolkit=tk)
+                all_tools.extend(paginated_tools.items)
+
+        # If no specific tools or toolkits were requested, retrieve *all* tools.
+        if not tools and not toolkits:
+            paginated_all_tools = self.client.tools.list()
+            all_tools.extend(paginated_all_tools.items)
+        # Build a dictionary that maps the "full_tool_name" to the tool definition.
+        tool_definitions: dict[str, ToolDefinition] = {}
+        for tool in all_tools:
+            # For items returned by .list(), the 'toolkit' and 'name' attributes
+            # should be present as plain fields on the object. (No need to do toolkit.name)
+            full_tool_name = f"{tool.toolkit.name}_{tool.name}"
+            tool_definitions[full_tool_name] = tool
+
+        return tool_definitions

langchain_arcade-1.0.0/pyproject.toml

@@ -0,0 +1,46 @@
+[tool.poetry]
+name = "langchain-arcade"
+version = "1.0.0"
+description = "An integration package connecting Arcade and LangChain/LangGraph"
+authors = ["Arcade AI <dev@arcade-ai.com>"]
+readme = "README.md"
+repository = "https://github.com/arcadeai/arcade-ai/tree/main/contrib/langchain"
+license = "MIT"
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.13"
+arcadepy = "^1.0.0"
+langgraph = ">=0.2.67,<0.3.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.1.2"
+pytest-cov = "^4.0.0"
+mypy = "^1.5.1"
+pre-commit = "^3.4.0"
+tox = "^4.11.1"
+pytest-asyncio = "^0.23.7"
+
+
+[tool.mypy]
+files = ["langchain_arcade"]
+python_version = "3.10"
+disallow_untyped_defs = "True"
+disallow_any_unimported = "True"
+no_implicit_optional = "True"
+check_untyped_defs = "True"
+warn_return_any = "True"
+warn_unused_ignores = "True"
+show_error_codes = "True"
+ignore_missing_imports = "True"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+
+[tool.coverage.run]
+branch = true
+source = ["langchain_arcade"]
+
+[tool.coverage.report]
+skip_empty = true