Add Compass Labs toolkits to langchain docs

docs/docs/integrations/tools/compass.ipynb

@@ -0,0 +1,346 @@
+{
+ "cells": [
+  {
+   "cell_type": "raw",
+   "id": "afaf8039",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "sidebar_label: Compass DeFi Toolkit\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e49f1e0d",
+   "metadata": {},
+   "source": [
+    "# Compass LangChain Toolkit\n",
+    "\n",
+    "Interact with various DeFi protocols. Non-custodial.",
+    "Tools return *unsigned transactions*. The toolkit is built on top of a Universal DeFi API ([Compass API](https://api.compasslabs.ai/)) allowing agents to perform financial operations like:\n",
+    "\n",
+    "- **Swapping tokens** on Uniswap and Aerodrome\n",
+    "- **Lending** or **borrowing** assets using protocols on Aave\n",
+    "- **Providing liquidity** on Aerodrome and Uniswap\n",
+    "- **Transferring funds** between wallets.\n",
+    "- Querying balances, portfolios and **monitoring positions**.\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "### Integration details\n",
+    "\n",
+    "| Class                    | Package             | Serializable | JS support |                                         Package latest                                         |\n",
+    "|:-------------------------|:--------------------| :---: | :---: |:----------------------------------------------------------------------------------------------:|\n",
+    "| LangchainCompassToolkit  | `langchain-compass` | ❌ | ❌ | ![PyPI - Version](https://img.shields.io/pypi/v/langchain-compass?style=flat-square&label=%20) |\n",
+    "\n",
+    "### Tool features\n",
+    "\n",
+    "Here’s a sample of the tools this toolkit provides (subject to change daily):\n",
+    "\n",
+    "- `aave_supply_`: Supply assets to Aave to earn interest.\n",
+    "- `aave_borrow_`: Borrow assets from Aave using collateral.\n",
+    "- `uniswap_swap_sell_exactly_`: Swap a specific amount of one token on Uniswap.\n",
+    "- `generic_portfolio_get_`: Retrieve a wallet’s portfolio in USD and token balances.\n",
+    "- `generic_transfer_erc20_`: Transfer ERC20 tokens between addresses.\n",
+    "\n",
+    "\n",
+    "## Setup\n",
+    "\n",
+    "Here we will:\n",
+    "\n",
+    "1. Install the langchain package\n",
+    "2. Import and instantiate the toolkit\n",
+    "3. Pass the tools to your agent with `toolkit.get_tools()`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0730d6a1",
+   "metadata": {},
+   "source": [
+    "### Installation\n",
+    "\n",
+    "This toolkit lives in the `langchain-compass` package:"
+   ]
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": "%pip install -qU langchain-compass",
+   "id": "652d6238"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a38cde65",
+   "metadata": {},
+   "source": [
+    "#### Environment Setup\n",
+    "\n",
+    "To run these examples, ensure LangChain has access to an LLM service. For instance, if you're using GPT-4o, create a `.env` file containing:\n",
+    "\n",
+    "```plaintext\n",
+    "# .env file\n",
+    "OPENAI_API_KEY=<your_openai_api_key_here>\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c5f2839",
+   "metadata": {},
+   "source": [
+    "### Instantiation\n",
+    "\n",
+    "Now we can instantiate our toolkit:"
+   ]
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-04-16T15:00:25.188941Z",
+     "start_time": "2025-04-16T15:00:23.842165Z"
+    }
+   },
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": 3,
+   "source": [
+    "from langchain_compass.toolkits import LangchainCompassToolkit\n",
+    "\n",
+    "toolkit = LangchainCompassToolkit(compass_api_key=None)"
+   ],
+   "id": "51a60dbe"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d11245ad",
+   "metadata": {},
+   "source": [
+    "### Tools\n",
+    "\n",
+    "View [available tools](#tool-features):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "310bf18e",
+   "metadata": {},
+   "source": [
+    "tools = toolkit.get_tools()\n",
+    "for tool in tools:\n",
+    "    print(tool.name)"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "```\n",
+    "# Expected output:\n",
+    "\n",
+    "aave_supply_\n",
+    "aave_borrow_\n",
+    "aave_repay_\n",
+    "aave_withdraw_\n",
+    "aave_asset_price_get_\n",
+    "aave_liquidity_change_get_\n",
+    "aave_user_position_summary_get_\n",
+    "...\n",
+    "```"
+   ],
+   "id": "c3fd41b52c203e03"
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## Invocation\n",
+    "\n",
+    "To invoke a single tool programmatically:"
+   ],
+   "id": "73b871e54cf1996"
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-04-16T15:16:33.924523Z",
+     "start_time": "2025-04-16T15:16:33.564016Z"
+    }
+   },
+   "cell_type": "code",
+   "source": [
+    "tool_name = \"generic_ens_get_\"\n",
+    "tool = next(tool for tool in tools if tool.name == tool_name)\n",
+    "tool.invoke({\"ens_name\": \"vitalik.eth\", \"chain\": \"ethereum:mainnet\"})"
+   ],
+   "id": "e384e604c38f07de",
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "EnsNameInfoResponse(wallet_address='0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', registrant='0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "execution_count": 13
+  },
+  {
+   "cell_type": "markdown",
+   "id": "23e11cc9",
+   "metadata": {},
+   "source": [
+    "## Use within an agent\n",
+    "\n",
+    "We will need a LLM or chat model:"
+   ]
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-04-16T15:00:27.027533Z",
+     "start_time": "2025-04-16T15:00:26.364789Z"
+    }
+   },
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": 5,
+   "source": [
+    "from dotenv import load_dotenv\n",
+    "from langchain_openai import ChatOpenAI\n",
+    "\n",
+    "load_dotenv()\n",
+    "\n",
+    "llm = ChatOpenAI(model=\"gpt-4o\")"
+   ],
+   "id": "d1ee55bc"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3a5bb5ca",
+   "metadata": {},
+   "source": [
+    "Initialize the agent with the tools:"
+   ]
+  },
+  {
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-04-16T15:00:27.948912Z",
+     "start_time": "2025-04-16T15:00:27.033842Z"
+    }
+   },
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": 6,
+   "source": [
+    "from langgraph.prebuilt import create_react_agent\n",
+    "\n",
+    "tools = toolkit.get_tools()\n",
+    "agent_executor = create_react_agent(llm, tools)"
+   ],
+   "id": "f8a2c4b1"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b4a7c9d2",
+   "metadata": {},
+   "source": "Example usage:"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": [
+    "example_query = \"please set an allowance on Uniswap of 10 WETH for vitalic.eth.\"  # spelt wrong intentionally\n",
+    "\n",
+    "events = agent_executor.stream(\n",
+    "    {\"messages\": [(\"user\", example_query)]},\n",
+    "    stream_mode=\"values\",\n",
+    ")\n",
+    "for event in events:\n",
+    "    event[\"messages\"][-1].pretty_print()"
+   ],
+   "id": "c9a8e4f3"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e5a7c9d4",
+   "metadata": {},
+   "source": [
+    "Expected output:\n",
+    "```\n",
+    "================================\u001B[1m Human Message \u001B[0m=================================\n",
+    "\n",
+    "please set an allowance on Uniswap of 10 WETH for vitalic.eth.\n",
+    "==================================\u001B[1m Ai Message \u001B[0m==================================\n",
+    "Tool Calls:\n",
+    "  generic_ens_get_ (call_MHIXRXxWH0L7iUEYHwvDUdU1)\n",
+    " Call ID: call_MHIXRXxWH0L7iUEYHwvDUdU1\n",
+    "  Args:\n",
+    "    chain: ethereum:mainnet\n",
+    "    ens_name: vitalic.eth\n",
+    "=================================\u001B[1m Tool Message \u001B[0m=================================\n",
+    "Name: generic_ens_get_\n",
+    "\n",
+    "wallet_address='0x44761Ef63FaD902D8f8dC77e559Ab116929881Db' registrant='0x44761Ef63FaD902D8f8dC77e559Ab116929881Db'\n",
+    "==================================\u001B[1m Ai Message \u001B[0m==================================\n",
+    "Tool Calls:\n",
+    "  generic_allowance_set_ (call_IEBftbtBfKCkI1zFXXtEY8tq)\n",
+    " Call ID: call_IEBftbtBfKCkI1zFXXtEY8tq\n",
+    "  Args:\n",
+    "    amount: 10\n",
+    "    chain: ethereum:mainnet\n",
+    "    contract_name: UniswapV3Router\n",
+    "    sender: 0x44761Ef63FaD902D8f8dC77e559Ab116929881Db\n",
+    "    token: WETH\n",
+    "=================================\u001B[1m Tool Message \u001B[0m=================================\n",
+    "Name: generic_allowance_set_\n",
+    "\n",
+    "{\"type\": \"unsigned_transaction\", \"content\": {\"chainId\": 1, \"data\": \"0x095ea7b300000000000000000000000068b3465833fb72a70ecdf485e0e4c7bd8665fc450000000000000000000000000000000000000000000000008ac7230489e80000\", \"from\": \"0x44761Ef63FaD902D8f8dC77e559Ab116929881Db\", \"gas\": 46434, \"to\": \"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2\", \"value\": 0, \"nonce\": 79, \"maxFeePerGas\": 2265376912, \"maxPriorityFeePerGas\": 6400594}}\n",
+    "\n",
+    "```"
+   ]
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## API reference\n",
+    "\n",
+    "`langchain-compass` is built on top of the Compass API. Each tool corresponds to an API endpoint. [Please check out the docs here](https://api.compasslabs.ai/)"
+   ],
+   "id": "2fe1ec8c22e5e79f"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}