docs: add payman docs (#29362)

- **Description:** Adding the docs to use the payman-langchain integration :)
langchain-ai · Jan 23, 2025 · f2ea62f · f2ea62f
1 parent 861024f
commit f2ea62f
Show file tree

Hide file tree

Showing 3 changed files with 309 additions and 0 deletions.
diff --git a/docs/docs/integrations/providers/payman-tool.mdx b/docs/docs/integrations/providers/payman-tool.mdx
@@ -0,0 +1,115 @@
+
+# PaymanAI
+
+PaymanAI provides functionality to send and receive payments (fiat and crypto) on behalf of an AI Agent. To get started:
+
+1. **Sign up** at app.paymanai.com to create an AI Agent and obtain your **API Key**.
+2. **Set** environment variables (`PAYMAN_API_SECRET` for your API Key, `PAYMAN_ENVIRONMENT` for sandbox or production).
+
+This notebook gives a quick overview of integrating PaymanAI into LangChain as a tool. For complete reference, see the API documentation.
+
+## Overview
+
+The PaymanAI integration is part of the `langchain-community` (or your custom) package. It allows you to:
+
+- Send payments (`send_payment`) to crypto addresses or bank accounts.
+- Search for payees (`search_payees`).
+- Add new payees (`add_payee`).
+- Request money from customers with a hosted checkout link (`ask_for_money`).
+- Check agent or customer balances (`get_balance`).
+
+These can be wrapped as **LangChain Tools** for an LLM-based agent to call them automatically.
+
+### Integration details
+
+| Class | Package | Serializable | JS support | Package latest |
+| :--- | :--- | :---: | :---: | :--- |
+| PaymanAI | `langchain_community` | ❌ | ❌ | [PyPI Version] |
+
+If you're simply calling the PaymanAI SDK, you can do it directly or via the **Tool** interface in LangChain.
+
+## Setup
+
+1. **Install** the `langchain-community` (or equivalent) package:
+
+```bash
+pip install --quiet -U langchain-community
+```
+
+2. **Install** the PaymanAI SDK:
+```bash
+pip install paymanai
+```
+
+3. **Set** environment variables:
+```bash
+export PAYMAN_API_SECRET="YOUR_SECRET_KEY"
+export PAYMAN_ENVIRONMENT="sandbox"
+```
+
+Your `PAYMAN_API_SECRET` should be the secret key from app.paymanai.com. The `PAYMAN_ENVIRONMENT` can be `sandbox` or `production` depending on your usage.
+
+## Instantiation
+
+Here is an example of instantiating a PaymanAI tool. If you have multiple Payman methods, you can create multiple tools.
+
+```python
+from langchain_community.tools.langchain_payman_tool.tool import PaymanAI
+
+# Instantiate the PaymanAI tool (example)
+tool = PaymanAI(
+    name="send_payment",
+    description="Send a payment to a specified payee.",
+)
+```
+
+## Invocation
+
+### Invoke directly with args
+
+You can call `tool.invoke(...)` and pass a dictionary matching the tool's expected fields. For example:
+
+```python
+response = tool.invoke({
+    "amount_decimal": 10.00,
+    "payment_destination_id": "abc123",
+    "customer_id": "cust_001",
+    "memo": "Payment for invoice #XYZ"
+})
+```
+
+### Invoke with ToolCall
+
+When used inside an AI workflow, the LLM might produce a `ToolCall` dict. You can simulate it as follows:
+
+```python
+model_generated_tool_call = {
+    "args": {
+        "amount_decimal": 10.00,
+        "payment_destination_id": "abc123"
+    },
+    "id": "1",
+    "name": tool.name,
+    "type": "tool_call",
+}
+tool.invoke(model_generated_tool_call)
+```
+
+## Using the Tool in a Chain or Agent
+
+You can bind a PaymanAI tool to a LangChain agent or chain that supports tool-calling.
+
+## Quick Start Summary
+
+1. **Sign up** at app.paymanai.com to get your **API Key**.
+2. **Install** dependencies:
+   ```bash
+   pip install paymanai langchain-community
+   ```
+3. **Export** environment variables:
+   ```bash
+   export PAYMAN_API_SECRET="YOUR_SECRET_KEY"
+   export PAYMAN_ENVIRONMENT="sandbox"
+   ```
+4. **Instantiate** a PaymanAI tool, passing your desired name/description.
+5. **Call** the tool with `.invoke(...)` or integrate it into a chain or agent.
diff --git a/docs/docs/integrations/tools/payman-tool.ipynb b/docs/docs/integrations/tools/payman-tool.ipynb
@@ -0,0 +1,189 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "# PaymanAI\n",
+    "\n",
+    "PaymanAI provides functionality to send and receive payments (fiat and crypto) on behalf of an AI Agent. To get started:\n",
+    "\n",
+    "1. **Sign up** at app.paymanai.com to create an AI Agent and obtain your **API Key**.\n",
+    "2. **Set** environment variables (`PAYMAN_API_SECRET` for your API Key, `PAYMAN_ENVIRONMENT` for sandbox or production).\n",
+    "\n",
+    "This notebook gives a quick overview of integrating PaymanAI into LangChain as a tool. For complete reference, see the API documentation.\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "The PaymanAI integration is part of the `langchain-community` (or your custom) package. It allows you to:\n",
+    "\n",
+    "- Send payments (`send_payment`) to crypto addresses or bank accounts.\n",
+    "- Search for payees (`search_payees`).\n",
+    "- Add new payees (`add_payee`).\n",
+    "- Request money from customers with a hosted checkout link (`ask_for_money`).\n",
+    "- Check agent or customer balances (`get_balance`).\n",
+    "\n",
+    "These can be wrapped as **LangChain Tools** for an LLM-based agent to call them automatically.\n",
+    "\n",
+    "### Integration details\n",
+    "\n",
+    "| Class | Package | Serializable | JS support | Package latest |\n",
+    "| :--- | :--- | :---: | :---: | :--- |\n",
+    "| PaymanAI | `langchain_community` | ❌ | ❌ | [PyPI Version] |\n",
+    "\n",
+    "If you're simply calling the PaymanAI SDK, you can do it directly or via the **Tool** interface in LangChain.\n",
+    "\n",
+    "## Setup\n",
+    "\n",
+    "1. **Install** the `langchain-community` (or equivalent) package:\n",
+    "\n",
+    "```bash\n",
+    "pip install --quiet -U langchain-community\n",
+    "```\n",
+    "\n",
+    "2. **Install** the PaymanAI SDK:\n",
+    "```bash\n",
+    "pip install paymanai\n",
+    "```\n",
+    "\n",
+    "3. **Set** environment variables:\n",
+    "```bash\n",
+    "export PAYMAN_API_SECRET=\"YOUR_SECRET_KEY\"\n",
+    "export PAYMAN_ENVIRONMENT=\"sandbox\"\n",
+    "```\n",
+    "\n",
+    "Your `PAYMAN_API_SECRET` should be the secret key from app.paymanai.com. The `PAYMAN_ENVIRONMENT` can be `sandbox` or `production` depending on your usage.\n",
+    "\n",
+    "## Instantiation\n",
+    "\n",
+    "Here is an example of instantiating a PaymanAI tool. If you have multiple Payman methods, you can create multiple tools.\n",
+    "\n",
+    "```python\n",
+    "from langchain_community.tools.langchain_payman_tool.tool import PaymanAI\n",
+    "\n",
+    "# Instantiate the PaymanAI tool (example)\n",
+    "tool = PaymanAI(\n",
+    "    name=\"send_payment\",\n",
+    "    description=\"Send a payment to a specified payee.\",\n",
+    ")\n",
+    "```\n",
+    "\n",
+    "## Invocation\n",
+    "\n",
+    "### Invoke directly with args\n",
+    "\n",
+    "You can call `tool.invoke(...)` and pass a dictionary matching the tool's expected fields. For example:\n",
+    "\n",
+    "```python\n",
+    "response = tool.invoke({\n",
+    "    \"amount_decimal\": 10.00,\n",
+    "    \"payment_destination_id\": \"abc123\",\n",
+    "    \"customer_id\": \"cust_001\",\n",
+    "    \"memo\": \"Payment for invoice #XYZ\"\n",
+    "})\n",
+    "```\n",
+    "\n",
+    "### Invoke with ToolCall\n",
+    "\n",
+    "When used inside an AI workflow, the LLM might produce a `ToolCall` dict. You can simulate it as follows:\n",
+    "\n",
+    "```python\n",
+    "model_generated_tool_call = {\n",
+    "    \"args\": {\n",
+    "        \"amount_decimal\": 10.00,\n",
+    "        \"payment_destination_id\": \"abc123\"\n",
+    "    },\n",
+    "    \"id\": \"1\",\n",
+    "    \"name\": tool.name,\n",
+    "    \"type\": \"tool_call\",\n",
+    "}\n",
+    "tool.invoke(model_generated_tool_call)\n",
+    "```\n",
+    "\n",
+    "## Using the Tool in a Chain or Agent\n",
+    "\n",
+    "You can bind a PaymanAI tool to a LangChain agent or chain that supports tool-calling.\n",
+    "\n",
+    "## Quick Start Summary\n",
+    "\n",
+    "1. **Sign up** at app.paymanai.com to get your **API Key**.\n",
+    "2. **Install** dependencies:\n",
+    "   ```bash\n",
+    "   pip install paymanai langchain-community\n",
+    "   ```\n",
+    "3. **Export** environment variables:\n",
+    "   ```bash\n",
+    "   export PAYMAN_API_SECRET=\"YOUR_SECRET_KEY\"\n",
+    "   export PAYMAN_ENVIRONMENT=\"sandbox\"\n",
+    "   ```\n",
+    "4. **Instantiate** a PaymanAI tool, passing your desired name/description.\n",
+    "5. **Call** the tool with `.invoke(...)` or integrate it into a chain or agent."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## API reference\n",
+    "\n",
+    "You can find full API documentation for PaymanAI at:\n",
+    "\n",
+    "- [Langchain-Payman Python reference](https://pypi.org/project/langchain-payman-tool/)\n",
+    "- [Payman Docs](https://docs.paymanai.com)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Chaining\n",
+    "\n",
+    "```python\n",
+    "from langchain_core.prompts import ChatPromptTemplate\n",
+    "from langchain_core.runnables import RunnableConfig, chain\n",
+    "from langchain.chat_models import init_chat_model\n",
+    "\n",
+    "# Assume we've imported your PaymanAITool or multiple Payman AI Tools\n",
+    "payman_tool = PaymanAITool(name=\"send_payment\")\n",
+    "\n",
+    "# Build a prompt\n",
+    "prompt = ChatPromptTemplate([\n",
+    "    (\"system\", \"You are a helpful AI that can send payments if asked.\"),\n",
+    "    (\"human\", \"{user_input}\"),\n",
+    "    (\"placeholder\", \"{messages}\"),\n",
+    "])\n",
+    "\n",
+    "llm = init_chat_model(model=\"gpt-4\", model_provider=\"openai\")\n",
+    "llm_with_tools = llm.bind_tools([payman_tool], tool_choice=payman_tool.name)\n",
+    "\n",
+    "llm_chain = prompt | llm_with_tools\n",
+    "\n",
+    "@chain\n",
+    "def tool_chain(user_input: str, config: RunnableConfig):\n",
+    "    input_ = {\"user_input\": user_input}\n",
+    "    ai_msg = llm_chain.invoke(input_, config=config)\n",
+    "    tool_msgs = payman_tool.batch(ai_msg.tool_calls, config=config)\n",
+    "    return llm_chain.invoke({**input_, \"messages\": [ai_msg, *tool_msgs]}, config=config)\n",
+    "\n",
+    "# Example usage:\n",
+    "response = tool_chain.invoke(\"Send $10 to payee123.\")\n",
+    "print(response)```\n",
+    "\n",
+    "## API reference\n",
+    "\n",
+    "You can find full API documentation for PaymanAI at:\n",
+    "\n",
+    "- [Python reference](https://python.langchain.com/v0.2/api_reference/community/tools/langchain_community.tools.langchain_payman_tool.tool.PaymanAI.html)\n",
+    "- (Any other relevant references or doc links)"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/libs/packages.yml b/libs/packages.yml
@@ -350,3 +350,8 @@ packages:
   path: .
   repo: pipeshift-org/langchain-pipeshift
   downloads: 115
+- name: langchain-payman-tool
+  path: .
+  repo: paymanai/langchain-payman-tool
+  downloads: 0
+  downloads_updated_at: "2025-01-22T00:00:00+00:00"