Getting started example

examples/index/getting-started-with-index.ipynb

@@ -0,0 +1,512 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "3atVJlcc1-Cb"
+      },
+      "source": [
+        "# Welcome to LlamaCloud Index!\n",
+        "\n",
+        "LlamaCloud Index is an enterprise service from LlamaIndex which makes it easy to load, parse, index and retrieve data and then use it in AI Agents built in our LlamaIndex open source framework.\n",
+        "\n",
+        "This notebook is part of a [video tutorial](https://youtu.be/fx4SeNc3RZE?feature=shared) showing you how to get started with LlamaCloud Index by creating your first index, loading data into it, setting up some configuration parameters, and then plugging that data into an agent.\n",
+        "\n",
+        "To do that, we'll walk you through a very simple agent built in LlamaIndex open source using our Workflows abstraction. This isn't intended to be a full workflows tutorial, but we'll provide you with some links to dive deeper.\n",
+        "\n",
+        "The dataset we'll be using today is a set of deposit account and rate agreements from JP Morgan Chase, a set of very dense and technical PDFs, perfect for getting an LLM to do the work of reading and understanding. If you want to create your own index, you can get the documents from Chase's website or right here:\n",
+        "* [Deposit account agreement](https://www.dropbox.com/scl/fi/b96krxnp0vqzd46i9a27h/chase-deposit-account-agreement.pdf?rlkey=702xiqbe4g24739v31iengfxj&dl=0)\n",
+        "* [Additional banking services fees](https://www.dropbox.com/scl/fi/835lauu0qa45vq37y62a5/chase-additional-banking-services-and-fees.pdf?rlkey=emy2k2qvelzdshvhuk57zz4wl&dl=0)\n",
+        "* [Current rate sheet](https://www.dropbox.com/scl/fi/h8twmxh8nk6h7d62n3xy4/chase-rate-sheets.pdf?rlkey=ebi42qyc67ixlyeijpxtugm15&dl=0)\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Video Tutorial\n",
+        "\n",
+        "Watch the video tutorial for this notebook:\n",
+        "\n",
+        "<div style=\"position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;\">\n",
+        "  <iframe style=\"position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;\"\n",
+        "    src=\"https://www.youtube.com/embed/Trsu_NJIfnw?si=5FrcqRuGwsO8gCo8\"\n",
+        "    title=\"LlamaCloud Index Demo Tutorial\"\n",
+        "    frameborder=\"0\"\n",
+        "    allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\"\n",
+        "    allowfullscreen>\n",
+        "  </iframe>\n",
+        "</div>"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "8hkCyM7V7rMy"
+      },
+      "source": [
+        "As always, we'll need to install our dependencies:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "collapsed": true,
+        "id": "sfj75Q0c7uK4",
+        "outputId": "e466fd52-b3c2-4449-a1a8-7677929b7415"
+      },
+      "outputs": [],
+      "source": [
+        "!pip install llama-index-indices-managed-llama-cloud llama-index-llms-anthropic llama-index-core"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "5D65l6kv2W3V"
+      },
+      "source": [
+        "To get started, we'll need two API keys:\n",
+        "* A `LLAMACLOUD_API_KEY` to access our index\n",
+        "* An `ANTHROPIC_API_KEY` to access the LLM we'll use to power our agent"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "iCoSInLzyCKa"
+      },
+      "outputs": [],
+      "source": [
+        "from google.colab import userdata\n",
+        "LLAMACLOUD_API_KEY = userdata.get('llamacloud-demo-video')\n",
+        "ANTHROPIC_API_KEY = userdata.get('anthropic-key')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "uEnbjqYm26UR"
+      },
+      "source": [
+        "Let's bring in our LlamaCloud Index:\n",
+        "\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "U7NXVbiX17AD"
+      },
+      "outputs": [],
+      "source": [
+        "from llama_index.indices.managed.llama_cloud import LlamaCloudIndex\n",
+        "\n",
+        "index = LlamaCloudIndex(\n",
+        "  name=\"demo-video-index-1\",\n",
+        "  project_name=\"Demo Project\",\n",
+        "  organization_id=\"e793a802-cb91-4e6a-bd49-61d0ba2ac5f9\",\n",
+        "  api_key=LLAMACLOUD_API_KEY\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "M85TA2HL3HvM"
+      },
+      "source": [
+        "We'll smoke-test our index to make sure there's data in it by running a basic retrieval:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "hSuwNSlS3MsZ",
+        "outputId": "a5609320-0b79-4db9-bea3-8ef38bcfd606"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Found 6 nodes\n",
+            "Node ID: 8703fd46-ae91-4542-b46b-f3bf95190693\n",
+            "Score: 0.9446333\n",
+            "File Name: chase additional banking services and fees.pdf\n",
+            "Page Label: 3\n",
+            "--------------------\n",
+            "Node ID: 0f226f14-384a-45c7-9d34-1fccfcb71f9a\n",
+            "Score: 0.8812988\n",
+            "File Name: chase additional banking services and fees.pdf\n",
+            "Page Label: 8\n",
+            "--------------------\n",
+            "Node ID: 877d22f0-711c-4817-a487-0084ef4dff71\n",
+            "Score: 0.82560414\n",
+            "File Name: chase additional banking services and fees.pdf\n",
+            "Page Label: 7\n",
+            "--------------------\n",
+            "Node ID: 9d31640a-b561-47b5-a518-0844c9855672\n",
+            "Score: 0.81524754\n",
+            "File Name: chase additional banking services and fees.pdf\n",
+            "Page Label: 5\n",
+            "--------------------\n",
+            "Node ID: 279cfd9c-bdd9-4b73-9791-96aa6bc32528\n",
+            "Score: 0.79732054\n",
+            "File Name: chase additional banking services and fees.pdf\n",
+            "Page Label: 2\n",
+            "--------------------\n",
+            "Node ID: f5c0df7c-b16d-4bcc-85aa-b79211b527e3\n",
+            "Score: 0.79675186\n",
+            "File Name: chase additional banking services and fees.pdf\n",
+            "Page Label: 6\n",
+            "--------------------\n"
+          ]
+        }
+      ],
+      "source": [
+        "query = \"What is the monthly service fee for Chase Total Checking\"\n",
+        "nodes = index.as_retriever().retrieve(query)\n",
+        "\n",
+        "print(\"Found \" + str(len(nodes)) + \" nodes\")\n",
+        "\n",
+        "for node in nodes:\n",
+        "    print(f\"Node ID: {node.node.id_}\")\n",
+        "    print(f\"Score: {node.score}\")\n",
+        "    print(f\"File Name: {node.node.metadata.get('file_name')}\")\n",
+        "    print(f\"Page Label: {node.node.metadata.get('page_label')}\")\n",
+        "    print(\"-\" * 20)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "9VdpZiQM86uj"
+      },
+      "source": [
+        "Great! Our index is returning the raw nodes for our query. If we want, we can even get a basic answer to our question by creating a query engine from the index.\n",
+        "\n",
+        "First we'll need to instantiate an LLM for the query engine to use:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "CRCQDFtM9PWU"
+      },
+      "outputs": [],
+      "source": [
+        "from llama_index.llms.anthropic import Anthropic\n",
+        "\n",
+        "llm = Anthropic(\n",
+        "    api_key=ANTHROPIC_API_KEY,\n",
+        "  \tmodel=\"claude-sonnet-4-20250514\",\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "uzI3Jwml9nQt"
+      },
+      "source": [
+        "Now we create a query engine and ask the question:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "zvriqVJF9m00",
+        "outputId": "78657347-10d4-463b-9997-cdfed69c10df"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "The monthly service fee for Chase Total Checking is **$12** (increasing to $15, effective August 24, 2025).\n",
+            "\n",
+            "However, you can avoid this monthly service fee by meeting any ONE of the following requirements during each monthly statement period:\n",
+            "\n",
+            "- Electronic deposits totaling $500 or more (such as payroll or government benefits through ACH, Real Time Payment, FedNow networks, or third-party services using Visa/Mastercard networks)\n",
+            "- **OR** maintain a daily balance of $1,500 or more in the account\n",
+            "- **OR** maintain an average beginning day balance of $5,000 or more across the account and any linked qualifying deposits/investments\n"
+          ]
+        }
+      ],
+      "source": [
+        "engine = index.as_query_engine(llm=llm)\n",
+        "response = engine.query(query)\n",
+        "print(response)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "52GZLbJ0ARFL"
+      },
+      "source": [
+        "But we can do more! These engines work by naively sending the entire query to the retriever in a single shot, and hoping the retrieved chunks are sufficient to answer the question. We can make an agent that can query the index and use the data in concert with tools to answer complex, multi-part questions."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "pQ_heAWIHDRa"
+      },
+      "source": [
+        "To get started, let's create the simplest possible tool: a function that can add two numbers."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "xGLAdUS-C2Sj"
+      },
+      "outputs": [],
+      "source": [
+        "def add(a: float, b: float) -> float:\n",
+        "    \"\"\"Add two numbers and returns the sum\"\"\"\n",
+        "    return a + b"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "isenB1IYHKEy"
+      },
+      "source": [
+        "Now we'll create a second tool, this one created from the query engine we made earlier."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "_Y-v0K2YD47g"
+      },
+      "outputs": [],
+      "source": [
+        "from llama_index.core.tools import QueryEngineTool\n",
+        "\n",
+        "jpmorgan = QueryEngineTool.from_defaults(\n",
+        "    query_engine=engine,\n",
+        "    name=\"JPMorganChaseTool\",\n",
+        "    description=\"Query documents about JP Morgan Chase bank rates, fees and procedures\",\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "BPzazVo6HO0o"
+      },
+      "source": [
+        "Now we'll instantiate a FunctionAgent and give it these two tools. To learn more about creating agents, check out our [agent tutorial](https://docs.llamaindex.ai/en/stable/understanding/agent/)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "E2L_OUP6Dgdu"
+      },
+      "outputs": [],
+      "source": [
+        "from llama_index.core.agent.workflow import FunctionAgent\n",
+        "\n",
+        "workflow = FunctionAgent(\n",
+        "    tools=[add,jpmorgan],\n",
+        "    llm=llm,\n",
+        "    system_prompt=\"You are an expert in JP Morgan Chase banking fees and procedures\"\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {
+        "id": "5895k8jtHaYQ"
+      },
+      "source": [
+        "Now we're ready to ask a really complicated question! To show what's happening under the hood, we'll be streaming our tool calls and the results of those tool calls from the agent as it happens. Check out our [streaming documentation](https://docs.llamaindex.ai/en/stable/understanding/agent/streaming/) for more on how this works."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "zY1KcrrsFe9X",
+        "outputId": "4ef692f8-80e2-4211-bf66-ab6fb0a528b0"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "--------------------\n",
+            "Tool called: JPMorganChaseTool\n",
+            "Tool arguments:\n",
+            "  input: Chase Total Checking overdraft fees NSF fees when transactions cause negative balance\n",
+            "----------\n",
+            "Tool output:  For Chase Total Checking accounts, here are the overdraft fees when transactions cause a negative balance:\n",
+            "\n",
+            "## Overdraft Fees\n",
+            "Chase charges a **$34 Overdraft Fee per transaction** during nightly processing, beginning with the first transaction that overdraws your account balance by more than $50. There is a maximum of 3 fees per business day, up to $102 total.\n",
+            "\n",
+            "## When Overdraft Fees Won't Be Charged\n",
+            "You won't be charged an Overdraft Fee in these situations:\n",
+            "\n",
+            "- **Chase Overdraft Assist**: No fee if you're overdrawn by $50 or less at the end of the business day, OR if you're overdrawn by more than $50 but bring your account balance to overdrawn by $50 or less by the end of the next business day (you have until 11 p.m. ET/8 p.m. PT to make a deposit or transfer)\n",
+            "\n",
+            "- **Small transactions**: No fee for transactions that are $5 or less\n",
+            "\n",
+            "- **Authorized transactions**: No fee if your debit card transaction was authorized when there was sufficient available balance in your account\n",
+            "\n",
+            "## What's Covered by Standard Overdraft Practice\n",
+            "The Standard Overdraft Practice covers:\n",
+            "- Checks and other transactions using your checking account number\n",
+            "- Recurring debit card transactions (like subscriptions or gym memberships)\n",
+            "- Automatic payments (recurring bills)\n",
+            "\n",
+            "## What's NOT Covered\n",
+            "Everyday debit card transactions (groceries, gas, dining) are NOT covered unless you specifically enroll in Chase Debit Card Coverage.\n",
+            "\n",
+            "Chase pays overdrafts at their discretion and does not guarantee they will always authorize or pay overdraft transactions. If they don't pay an overdraft, the transaction will be declined or returned.\n",
+            "--------------------\n",
+            "Tool called: JPMorganChaseTool\n",
+            "Tool arguments:\n",
+            "  input: Chase debit card replacement fee rush delivery cost\n",
+            "----------\n",
+            "Tool output:  The cost for rush delivery of a replacement Chase debit card is **$15 per card, upon request**.\n",
+            "\n",
+            "This fee applies when you request express shipping of a replacement debit or ATM card. You can avoid this fee by requesting standard shipping instead.\n",
+            "\n",
+            "This rush delivery fee applies to most Chase account types, including Chase First Checking accounts. However, some premium account types like Chase Sapphire Checking and Chase Private Client Checking waive this fee as part of their benefits.\n",
+            "--------------------\n",
+            "Tool called: JPMorganChaseTool\n",
+            "Tool arguments:\n",
+            "  input: Chase stop payment fee cost phone banker\n",
+            "----------\n",
+            "Tool output:  The stop payment fee when you contact Chase and a banker places your stop payment request on a check or ACH is $30 per request.\n",
+            "\n",
+            "If you use chase.com, Chase Mobile, or the automated phone system to place a stop payment on a check, the fee is $25 per request. However, only some types of stop payments are available through these online and automated channels.\n",
+            "--------------------\n",
+            "Tool called: add\n",
+            "Tool arguments:\n",
+            "  a: 15\n",
+            "  b: 30\n",
+            "----------\n",
+            "Tool output:  45\n"
+          ]
+        }
+      ],
+      "source": [
+        "from llama_index.core.agent.workflow import (\n",
+        "    AgentOutput,\n",
+        "    ToolCallResult,\n",
+        ")\n",
+        "\n",
+        "handler = workflow.run(\"\"\"You have a Chase Total Checking account with $25 in your balance on\n",
+        "Monday morning. Throughout Monday, you make a $15 grocery purchase (debit card),\n",
+        "write a $20 check that gets cashed, and have a $25 automatic utility bill payment (ACH)\n",
+        "that processes. On Tuesday, you request a rush replacement for your lost debit card and\n",
+        "place a stop payment on another check over the phone with a banker. What is the total\n",
+        "amount in fees you would be charged, and when would each fee be assessed?\"\"\")\n",
+        "\n",
+        "# handle streaming output\n",
+        "async for event in handler.stream_events():\n",
+        "    if isinstance(event, AgentOutput):\n",
+        "        for tool_call in event.tool_calls:\n",
+        "            print(\"-\" * 20)\n",
+        "            print(\"Tool called: \" + tool_call.tool_name)\n",
+        "            print(\"Tool arguments:\")\n",
+        "            # Print all keys and values in tool_call.tool_kwargs\n",
+        "            for key, value in tool_call.tool_kwargs.items():\n",
+        "                print(f\"  {key}: {value}\")\n",
+        "            print(\"-\" * 10)\n",
+        "    elif isinstance(event, ToolCallResult):\n",
+        "        print(\"Tool output: \", event.tool_output)  # the tool output"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "ga5KB--EEkK8",
+        "outputId": "8bc617ca-80a9-4377-aaf6-05324237cfe9"
+      },
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Based on the Chase Total Checking fee structure, here's what would happen in your scenario:\n",
+            "\n",
+            "## Monday Transactions Analysis:\n",
+            "**Starting balance:** $25\n",
+            "\n",
+            "1. **$15 grocery purchase (debit card)** - This would likely be **declined** since everyday debit card transactions are NOT covered by Chase's Standard Overdraft Practice unless you specifically enrolled in Chase Debit Card Coverage.\n",
+            "\n",
+            "2. **$20 check cashed** - Balance becomes $5 ($25 - $20)\n",
+            "\n",
+            "3. **$25 automatic utility bill payment (ACH)** - Balance becomes -$20 ($5 - $25)\n",
+            "\n",
+            "## Overdraft Fee Assessment:\n",
+            "Since your account would be overdrawn by only $20 (which is less than $50), **Chase Overdraft Assist applies** - you would **NOT be charged the $34 overdraft fee** as long as the overdraft is $50 or less.\n",
+            "\n",
+            "## Tuesday Fees:\n",
+            "1. **Rush debit card replacement:** $15\n",
+            "2. **Stop payment via phone with banker:** $30\n",
+            "\n",
+            "## Total Fees: $45\n",
+            "\n",
+            "**Fee Assessment Timeline:**\n",
+            "- **Monday:** $0 in overdraft fees (protected by Chase Overdraft Assist)\n",
+            "- **Tuesday:** $45 total ($15 for rush card replacement + $30 for stop payment)\n",
+            "\n",
+            "The key factor here is that Chase Overdraft Assist protects you from overdraft fees when you're overdrawn by $50 or less, which saves you from what would otherwise be a $34 overdraft fee on the utility payment.\n"
+          ]
+        }
+      ],
+      "source": [
+        "print(str(await handler))"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "provenance": []
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}