langchain-arcade 1.1.0__tar.gz → 1.2.0__tar.gz

langchain_arcade-1.2.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.1
+Name: langchain-arcade
+Version: 1.2.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
+Author-email: dev@arcade.dev
+Requires-Python: >=3.10,<4
+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
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: arcadepy (==1.1.*)
+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.dev/images/logo/arcade-logo.png"
+  >
+</h3>
+<div align="center">
+  <h3>Arcade Langchain Integration</h3>
+    <a href="https://github.com/arcadeai/langchain-arcade/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 href="https://pypi.org/project/langchain-arcade/">
+    <img src="https://img.shields.io/pypi/v/langchain-arcade.svg" alt="PyPI">
+  </a>
+</a>
+
+</div>
+
+<p align="center">
+    <a href="https://docs.arcade.dev" target="_blank">Arcade Documentation</a> •
+    <a href="https://docs.arcade.dev/toolkits" target="_blank">Toolkits</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 tools in your LangChain and LangGraph applications. This integration provides a simple way to access Arcade's extensive toolkit ecosystem, including tools for search, email, document processing, and more.
+
+## Installation
+
+```bash
+pip install langchain-arcade
+```
+
+## Basic Usage
+
+### 1. Initialize the Tool Manager
+
+The `ToolManager` is the main entry point for working with Arcade tools in LangChain:
+
+```python
+import os
+from langchain_arcade import ToolManager
+
+# Initialize with your API key
+manager = ToolManager(api_key=os.environ["ARCADE_API_KEY"])
+
+# Initialize with specific tools or toolkits
+tools = manager.init_tools(
+    tools=["Web.ScrapeUrl"],     # Individual tools
+    toolkits=["Search"]          # All tools from a toolkit
+)
+
+# Convert to LangChain tools
+langchain_tools = manager.to_langchain()
+```
+
+### 2. Use with LangGraph
+
+Here's a simple example of using Arcade tools with LangGraph:
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.prebuilt import create_react_agent
+
+# Create a LangGraph agent
+model = ChatOpenAI(model="gpt-4o")
+memory = MemorySaver()
+graph = create_react_agent(model, tools, checkpointer=memory)
+
+config = {"configurable": {"thread_id": "1", "user_id": "user@example.com"}}
+user_input = {"messages": [("user", "List my important emails")]}
+
+for chunk in graph.stream(user_input, config, stream_mode="values"):
+    print(chunk["messages"][-1].content)
+```
+
+## Using Tools with Authorization in LangGraph
+
+Many Arcade tools require user authorization. Here's how to handle it:
+
+### 1. Using with prebuilt agents
+
+```python
+import os
+
+from langchain_arcade import ToolManager
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+# Initialize tools
+manager = ToolManager(api_key=os.environ["ARCADE_API_KEY"])
+manager.init_tools(toolkits=["Github"])
+tools = manager.to_langchain(use_interrupts=True)
+
+# Create agent
+model = ChatOpenAI(model="gpt-4o")
+graph = create_react_agent(model, tools)
+
+# Run the agent with the "user_id" field in the config
+# IMPORTANT the "user_id" field is required for tools that require user authorization
+config = {"configurable": {"user_id": "user@lgexample.com"}}
+user_input = {"messages": [("user", "Star the arcadeai/arcade-ai repository on GitHub")]}
+
+for chunk in graph.stream(user_input, config, debug=True):
+    if chunk.get("__interrupt__"):
+        # print the authorization url
+        print(chunk["__interrupt__"][0].value)
+        # visit the URL to authorize the tool
+        # once you have authorized the tool, you can run again and the agent will continue
+    elif chunk.get("agent"):
+        print(chunk["agent"]["messages"][-1].content)
+
+# see the functional example for continuing the agent after authorization
+# and for handling authorization errors gracefully
+
+```
+
+See the Functional examples in the [examples directory](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/langchain) that continue the agent after authorization and handle authorization errors gracefully.
+
+### Async Support
+
+For asynchronous applications, use `AsyncToolManager`:
+
+```python
+import asyncio
+from langchain_arcade import AsyncToolManager
+
+async def main():
+    manager = AsyncToolManager(api_key=os.environ["ARCADE_API_KEY"])
+    await manager.init_tools(toolkits=["Google"])
+    tools = await manager.to_langchain()
+
+    # Use tools with async LangChain/LangGraph components
+
+asyncio.run(main())
+```
+
+## Tool Authorization Flow
+
+Many Arcade tools require user authorization. This can be handled in many ways but the `ToolManager` provides a simple flow that can be used with prebuilt agents and also the functional API. The typical flow is:
+
+1. Attempt to use a tool that requires authorization
+2. Check the state for interrupts from the `NodeInterrupt` exception (or Command)
+3. Call `manager.authorize(tool_name, user_id)` to get an authorization URL
+4. Present the URL to the user
+5. Call `manager.wait_for_auth(auth_response.id)` to wait for completion
+6. Resume the agent execution
+
+## Available Toolkits
+
+Arcade provides many toolkits including:
+
+-   `Search`: Google search, Bing search
+-   `Google`: Gmail, Google Drive, Google Calendar
+-   `Web`: Crawling, scraping, etc
+-   `Github`: Repository operations
+-   `Slack`: Sending messages to Slack
+-   `Linkedin`: Posting to Linkedin
+-   `X`: Posting and reading tweets on X
+-   And many more
+
+For a complete list, see the [Arcade Toolkits documentation](https://docs.arcade.dev/toolkits).
+
+## More Examples
+
+For more examples, see the [examples directory](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/langchain).
+

langchain_arcade-1.2.0/README.md

@@ -0,0 +1,171 @@
+<h3 align="center">
+  <a name="readme-top"></a>
+  <img
+    src="https://docs.arcade.dev/images/logo/arcade-logo.png"
+  >
+</h3>
+<div align="center">
+  <h3>Arcade Langchain Integration</h3>
+    <a href="https://github.com/arcadeai/langchain-arcade/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 href="https://pypi.org/project/langchain-arcade/">
+    <img src="https://img.shields.io/pypi/v/langchain-arcade.svg" alt="PyPI">
+  </a>
+</a>
+
+</div>
+
+<p align="center">
+    <a href="https://docs.arcade.dev" target="_blank">Arcade Documentation</a> •
+    <a href="https://docs.arcade.dev/toolkits" target="_blank">Toolkits</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 tools in your LangChain and LangGraph applications. This integration provides a simple way to access Arcade's extensive toolkit ecosystem, including tools for search, email, document processing, and more.
+
+## Installation
+
+```bash
+pip install langchain-arcade
+```
+
+## Basic Usage
+
+### 1. Initialize the Tool Manager
+
+The `ToolManager` is the main entry point for working with Arcade tools in LangChain:
+
+```python
+import os
+from langchain_arcade import ToolManager
+
+# Initialize with your API key
+manager = ToolManager(api_key=os.environ["ARCADE_API_KEY"])
+
+# Initialize with specific tools or toolkits
+tools = manager.init_tools(
+    tools=["Web.ScrapeUrl"],     # Individual tools
+    toolkits=["Search"]          # All tools from a toolkit
+)
+
+# Convert to LangChain tools
+langchain_tools = manager.to_langchain()
+```
+
+### 2. Use with LangGraph
+
+Here's a simple example of using Arcade tools with LangGraph:
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.prebuilt import create_react_agent
+
+# Create a LangGraph agent
+model = ChatOpenAI(model="gpt-4o")
+memory = MemorySaver()
+graph = create_react_agent(model, tools, checkpointer=memory)
+
+config = {"configurable": {"thread_id": "1", "user_id": "user@example.com"}}
+user_input = {"messages": [("user", "List my important emails")]}
+
+for chunk in graph.stream(user_input, config, stream_mode="values"):
+    print(chunk["messages"][-1].content)
+```
+
+## Using Tools with Authorization in LangGraph
+
+Many Arcade tools require user authorization. Here's how to handle it:
+
+### 1. Using with prebuilt agents
+
+```python
+import os
+
+from langchain_arcade import ToolManager
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+# Initialize tools
+manager = ToolManager(api_key=os.environ["ARCADE_API_KEY"])
+manager.init_tools(toolkits=["Github"])
+tools = manager.to_langchain(use_interrupts=True)
+
+# Create agent
+model = ChatOpenAI(model="gpt-4o")
+graph = create_react_agent(model, tools)
+
+# Run the agent with the "user_id" field in the config
+# IMPORTANT the "user_id" field is required for tools that require user authorization
+config = {"configurable": {"user_id": "user@lgexample.com"}}
+user_input = {"messages": [("user", "Star the arcadeai/arcade-ai repository on GitHub")]}
+
+for chunk in graph.stream(user_input, config, debug=True):
+    if chunk.get("__interrupt__"):
+        # print the authorization url
+        print(chunk["__interrupt__"][0].value)
+        # visit the URL to authorize the tool
+        # once you have authorized the tool, you can run again and the agent will continue
+    elif chunk.get("agent"):
+        print(chunk["agent"]["messages"][-1].content)
+
+# see the functional example for continuing the agent after authorization
+# and for handling authorization errors gracefully
+
+```
+
+See the Functional examples in the [examples directory](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/langchain) that continue the agent after authorization and handle authorization errors gracefully.
+
+### Async Support
+
+For asynchronous applications, use `AsyncToolManager`:
+
+```python
+import asyncio
+from langchain_arcade import AsyncToolManager
+
+async def main():
+    manager = AsyncToolManager(api_key=os.environ["ARCADE_API_KEY"])
+    await manager.init_tools(toolkits=["Google"])
+    tools = await manager.to_langchain()
+
+    # Use tools with async LangChain/LangGraph components
+
+asyncio.run(main())
+```
+
+## Tool Authorization Flow
+
+Many Arcade tools require user authorization. This can be handled in many ways but the `ToolManager` provides a simple flow that can be used with prebuilt agents and also the functional API. The typical flow is:
+
+1. Attempt to use a tool that requires authorization
+2. Check the state for interrupts from the `NodeInterrupt` exception (or Command)
+3. Call `manager.authorize(tool_name, user_id)` to get an authorization URL
+4. Present the URL to the user
+5. Call `manager.wait_for_auth(auth_response.id)` to wait for completion
+6. Resume the agent execution
+
+## Available Toolkits
+
+Arcade provides many toolkits including:
+
+-   `Search`: Google search, Bing search
+-   `Google`: Gmail, Google Drive, Google Calendar
+-   `Web`: Crawling, scraping, etc
+-   `Github`: Repository operations
+-   `Slack`: Sending messages to Slack
+-   `Linkedin`: Posting to Linkedin
+-   `X`: Posting and reading tweets on X
+-   And many more
+
+For a complete list, see the [Arcade Toolkits documentation](https://docs.arcade.dev/toolkits).
+
+## More Examples
+
+For more examples, see the [examples directory](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/langchain).

langchain_arcade-1.2.0/langchain_arcade/__init__.py

@@ -0,0 +1,7 @@
+from .manager import ArcadeToolManager, AsyncToolManager, ToolManager
+
+__all__ = [
+    "ToolManager",
+    "AsyncToolManager",
+    "ArcadeToolManager",  # Deprecated
+]

{langchain_arcade-1.1.0 → langchain_arcade-1.2.0}/langchain_arcade/_utilities.py

@@ -1,7 +1,7 @@
-from typing import Any, Callable
+from typing import Any, Callable, Union
 
-from arcadepy import NOT_GIVEN, Arcade
-from arcadepy.types import ToolDefinition
+from arcadepy import NOT_GIVEN, Arcade, AsyncArcade
+from arcadepy.types import ExecuteToolResponse, ToolDefinition
 from langchain_core.runnables import RunnableConfig
 from langchain_core.tools import StructuredTool
 from pydantic import BaseModel, Field, create_model
@@ -68,6 +68,51 @@ def tool_definition_to_pydantic_model(tool_def: ToolDefinition) -> type[BaseMode
         )
 
 
+def process_tool_execution_response(
+    execute_response: ExecuteToolResponse, tool_name: str, langgraph: bool
+) -> Any:
+    """Process the response from tool execution and handle errors appropriately.
+
+    Args:
+        execute_response: The response from tool execution
+        tool_name: The name of the tool that was executed
+        langgraph: Whether LangGraph-specific behavior is enabled
+
+    Returns:
+        The output value on success, or error details on failure
+    """
+    if execute_response.success and execute_response.output is not None:
+        return execute_response.output.value
+
+    # Extract detailed error information
+    error_details = {
+        "error": "Unknown error occurred",
+        "tool": tool_name,
+    }
+
+    if execute_response.output is not None and execute_response.output.error is not None:
+        error = execute_response.output.error
+        error_message = str(error.message) if hasattr(error, "message") else "Unknown error"
+        error_details["error"] = error_message
+
+        # Add all non-None optional error fields to the details
+        if (
+            hasattr(error, "additional_prompt_content")
+            and error.additional_prompt_content is not None
+        ):
+            error_details["additional_prompt_content"] = error.additional_prompt_content
+        if hasattr(error, "can_retry") and error.can_retry is not None:
+            error_details["can_retry"] = str(error.can_retry)
+        if hasattr(error, "developer_message") and error.developer_message is not None:
+            error_details["developer_message"] = str(error.developer_message)
+        if hasattr(error, "retry_after_ms") and error.retry_after_ms is not None:
+            error_details["retry_after_ms"] = str(error.retry_after_ms)
+
+    if langgraph:
+        raise NodeInterrupt(error_details)
+    return error_details
+
+
 def create_tool_function(
     client: Arcade,
     tool_name: str,
@@ -128,18 +173,13 @@ def create_tool_function(
             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 process_tool_execution_response(execute_response, tool_name, langgraph)
 
     return tool_function
 
 
 def wrap_arcade_tool(
-    client: Arcade,
+    client: Union[Arcade, AsyncArcade],
     tool_name: str,
     tool_def: ToolDefinition,
     langgraph: bool = False,
@@ -161,13 +201,23 @@ def wrap_arcade_tool(
     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,
-    )
+    if isinstance(client, Arcade):
+        action_func = create_tool_function(
+            client=client,
+            tool_name=tool_name,
+            tool_def=tool_def,
+            args_schema=args_schema,
+            langgraph=langgraph,
+        )
+    else:
+        # Use async tool function for AsyncArcade client
+        action_func = create_async_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(
@@ -177,3 +227,68 @@ def wrap_arcade_tool(
         args_schema=args_schema,
         inject_kwargs={"user_id"},
     )
+
+
+def create_async_tool_function(
+    client: AsyncArcade,
+    tool_name: str,
+    tool_def: ToolDefinition,
+    args_schema: type[BaseModel],
+    langgraph: bool = False,
+) -> Callable:
+    """Create an async callable function to execute an Arcade tool.
+
+    Args:
+        client: The AsyncArcade 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:
+        An async 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
+    )
+
+    async def tool_function(config: RunnableConfig, **kwargs: Any) -> Any:
+        """Run 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 = await 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 = await client.tools.execute(
+            tool_name=tool_name,
+            input=kwargs,
+            user_id=user_id if user_id is not None else NOT_GIVEN,
+        )
+
+        return process_tool_execution_response(execute_response, tool_name, langgraph)
+
+    return tool_function