diff --git a/docs/docs/integrations/tools/compass.ipynb b/docs/docs/integrations/tools/compass.ipynb new file mode 100644 index 00000000000..9e316cee0d6 --- /dev/null +++ b/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=\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 +}