From f2ea62f63209130bfc56b1fe7d0fa7c299bbf352 Mon Sep 17 00:00:00 2001 From: Tyllen <43430513+tyllenb@users.noreply.github.com> Date: Wed, 22 Jan 2025 19:37:47 -0700 Subject: [PATCH] docs: add payman docs (#29362) - **Description:** Adding the docs to use the payman-langchain integration :) --- .../integrations/providers/payman-tool.mdx | 115 +++++++++++ .../docs/integrations/tools/payman-tool.ipynb | 189 ++++++++++++++++++ libs/packages.yml | 5 + 3 files changed, 309 insertions(+) create mode 100644 docs/docs/integrations/providers/payman-tool.mdx create mode 100644 docs/docs/integrations/tools/payman-tool.ipynb diff --git a/docs/docs/integrations/providers/payman-tool.mdx b/docs/docs/integrations/providers/payman-tool.mdx new file mode 100644 index 0000000000000..a6a33befe5cea --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/docs/integrations/tools/payman-tool.ipynb b/docs/docs/integrations/tools/payman-tool.ipynb new file mode 100644 index 0000000000000..92292c1d57f8d --- /dev/null +++ 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 index 56772c962b7e0..1cb609c30841e 100644 --- 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" \ No newline at end of file