tracing-examples/traceable/tracing_without_langchain.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "79036a8c",
   "metadata": {
    "tags": []
   },
   "source": [
    "# Tracing without LangChain\n",
    "[![Open In Collab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/langchain-ai/langsmith-cookbook/blob/main/tracing-examples/traceable/tracing_without_langchain.ipynb)\n",
    "\n",
    "LangSmith lets you instrument **any LLM application,** no LangChain required. This aids in debugging, evaluating, and monitoring your app, without needing to learn any particular framework's unique semantics.\n",
    "\n",
    "LangSmith instruments your apps through run traces. Each trace is made of 1 or more \"runs\" representing key event spans in your app. Each run is a structured log with a name, `run_type`, inputs / outputs, start/end times, as well as tags and other metadata. Runs within a trace are nested, forming a hierarchy referred to as a \"run tree.\"\n",
    "\n",
    "In Python, LangSmith offers two ways to help manage run trees:\n",
    "\n",
    "1. `RunTree` object: manages run data and communicates with the LangSmith platform. The `create_child` method simplifies the creation and organization of child runs within the hierarchy.\n",
    "2. `@traceable` decorator: automates the process of instrumenting function calls, handling the RunTree lifecycle for you.\n",
    "\n",
    "This walkthrough guides you through creating a chat app and instrumenting it with the `@traceable` decorator. You will add tags and other metadata to your runs to help filter and organize the resulting traces. The chat app uses three 'chain' components to generate a text argument on a provided subject:\n",
    "\n",
    "1. An argument generation function\n",
    "2. Critique function\n",
    "3. Refine function\n",
    "\n",
    "Each of these functions will call an openai `llm` function, and the whole series of calls will itself be organized beneath a parent `argument_chain` function, generating a trace like this:\n",
    "\n",
    "![RunTree 1](img/snapshot_1.png)\n",
    "\n",
    "Ready to build? Let's start!\n",
    "\n",
    "## Prerequisites\n",
    "\n",
    "Let's first install the required packages. The app uses `openai`'s SDK, and our tracing will use the `langsmith` SDK.\n",
    "\n",
    "Install the latest versions to make sure you have all the required updates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5615479e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# %pip install -U langsmith > /dev/null\n",
    "# %pip install -U openai > /dev/null"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06ebe2c0",
   "metadata": {},
   "source": [
    "Next, configure the API Key in the environment to make sure traces are logged to your account."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "f665dbcd",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "# Update with your API URL if using a hosted instance of Langsmith.\n",
    "os.environ[\"LANGCHAIN_ENDPOINT\"] = \"https://api.smith.langchain.com\"\n",
    "os.environ[\"LANGCHAIN_API_KEY\"] = \"YOUR API KEY\"  # Update with your API key\n",
    "os.environ[\"LANGCHAIN_TRACING_V2\"] = \"true\"\n",
    "project_name = \"YOUR PROJECT NAME\"  # Update with your project name\n",
    "os.environ[\"LANGCHAIN_PROJECT\"] = project_name  # Optional: \"default\" is used if not set\n",
    "os.environ[\"OPENAI_API_KEY\"] = \"YOUR OPENAI API KEY\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17285047",
   "metadata": {},
   "source": [
    "## Using the decorator\n",
    "\n",
    "Next, define your chat application. Use the `@traceable` decorator to automatically instrument your\n",
    "function calls.\n",
    "\n",
    "The decorator works by creating a run tree for you each time the function is called and inserting it within the current trace. The function inputs, name, and other information is then streamed to LangSmith. If the function raises an error or if it returns a response, that information is also added to the tree, and updates are patched to LangSmith so you can detect and diagnose sources of errors. This is all done on a background thread to avoid blocking your app's execution.\n",
    "\n",
    "The app below combines three runs with the \"chain\" `run_type`. Run types can be thought of as a special type of tags to help index and visualize the logged information. Each of our \"chain\" runs call an function typed as an \"llm\" run. These correspond LLM or chat model calls. We recommend you type most functions as `chain` runs, as these are the most general-purpose."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "4ba8c359",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from datetime import datetime\n",
    "from typing import List, Optional, Tuple\n",
    "\n",
    "from openai import OpenAI\n",
    "from langsmith.run_helpers import traceable\n",
    "\n",
    "openai_client = OpenAI()\n",
    "\n",
    "\n",
    "# We will label this function as an 'llm' call to better organize it\n",
    "@traceable(run_type=\"llm\")\n",
    "def call_openai(\n",
    "    messages: List[dict], model: str = \"gpt-3.5-turbo\", temperature: float = 0.0\n",
    ") -> str:\n",
    "    return openai_client.chat.completions.create(\n",
    "        model=model,\n",
    "        messages=messages,\n",
    "        temperature=temperature,\n",
    "    )\n",
    "\n",
    "\n",
    "# The 'chain' run_type can correspond to any function and is the most common\n",
    "@traceable(run_type=\"chain\")\n",
    "def argument_generator(query: str, additional_description: str = \"\") -> str:\n",
    "    return (\n",
    "        call_openai(\n",
    "            [\n",
    "                {\n",
    "                    \"role\": \"system\",\n",
    "                    \"content\": f\"You are a debater making an argument on a topic.\"\n",
    "                    f\"{additional_description}\"\n",
    "                    f\" The current time is {datetime.now()}\",\n",
    "                },\n",
    "                {\"role\": \"user\", \"content\": f\"The discussion topic is {query}\"},\n",
    "            ]\n",
    "        )\n",
    "        .choices[0]\n",
    "        .message.content\n",
    "    )\n",
    "\n",
    "\n",
    "@traceable(run_type=\"chain\")\n",
    "def critic(argument: str) -> str:\n",
    "    return (\n",
    "        call_openai(\n",
    "            [\n",
    "                {\n",
    "                    \"role\": \"system\",\n",
    "                    \"content\": f\"You are a critic.\"\n",
    "                    \"\\nWhat unresolved questions or criticism do you have after reading the following argument?\"\n",
    "                    \"Provide a concise summary of your feedback.\",\n",
    "                },\n",
    "                {\"role\": \"system\", \"content\": argument},\n",
    "            ]\n",
    "        )\n",
    "        .choices[0]\n",
    "        .message.content\n",
    "    )\n",
    "\n",
    "\n",
    "@traceable(run_type=\"chain\")\n",
    "def refiner(\n",
    "    query: str, additional_description: str, current_arg: str, criticism: str\n",
    ") -> str:\n",
    "    return (\n",
    "        call_openai(\n",
    "            [\n",
    "                {\n",
    "                    \"role\": \"system\",\n",
    "                    \"content\": f\"You are a debater making an argument on a topic.\"\n",
    "                    f\"{additional_description}\"\n",
    "                    f\" The current time is {datetime.now()}\",\n",
    "                },\n",
    "                {\"role\": \"user\", \"content\": f\"The discussion topic is {query}\"},\n",
    "                {\"role\": \"assistant\", \"content\": current_arg},\n",
    "                {\"role\": \"user\", \"content\": criticism},\n",
    "                {\n",
    "                    \"role\": \"system\",\n",
    "                    \"content\": \"Please generate a new argument that incorporates the feedback from the user.\",\n",
    "                },\n",
    "            ]\n",
    "        )\n",
    "        .choices[0]\n",
    "        .message.content\n",
    "    )\n",
    "\n",
    "\n",
    "@traceable(run_type=\"chain\")\n",
    "def argument_chain(query: str, additional_description: str = \"\") -> str:\n",
    "    argument = argument_generator(query, additional_description)\n",
    "    criticism = critic(argument)\n",
    "    return refiner(query, additional_description, argument, criticism)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97fb9f73",
   "metadata": {},
   "source": [
    "Now call the chain. If you set up your API key correctly at the start of this notebook, all the results should be traced to [LangSmith](https://smith.langchain.com). We will prompt the app to generate an argument that sunshine is good for you."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "6f5798a7",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Sunshine, when enjoyed responsibly, offers numerous benefits for overall health and well-being. It is a natural source of vitamin D, which plays a vital role in bone health, immune function, and mental well-being. While excessive sun exposure can lead to sunburns and increase the risk of skin damage and cancer, moderate and safe sun exposure, along with proper sun protection measures, can help maximize the benefits while minimizing the risks. It is important to strike a balance and make informed choices to harness the positive effects of sunshine while taking necessary precautions to protect our skin.\n"
     ]
    }
   ],
   "source": [
    "result = argument_chain(\n",
    "    \"Whether sunshine is good for you.\",\n",
    "    additional_description=\"Provide a concise, few sentence argument on why sunshine is good for you.\",\n",
    ")\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3cad8af8",
   "metadata": {},
   "source": [
    "## Working with runs\n",
    "\n",
    "The above is all you need to save your app traces to LangSmith! You can try changing the functions or even raising errors in the above code to see how it's visualized in [LangSmith](https://smith.langchain.com).\n",
    "\n",
    "The decorator does all this work behind the scenes, but you may want to be able to actually use the run ID for other things like monitoring user feedback or logging to another destination. You can easily do this by modifying your function signature to accept a `run_tree` keyword argument. Doing so will instuct the `@traceable` decorator to inject the current run tree object into your function. This can be useful if you want to:\n",
    "- Add user feedback to the run\n",
    "- Inspect or save the run ID or its parent\n",
    "- Manually log child runs or their information to another destination\n",
    "- Continue a trace in other functions that may be called within a separate thread or process pool (or even on separate machines)\n",
    "\n",
    "Below, our `argument_chain2` function is identical to the previous one except that we return the ID of the `run_tree` for use outside the function context."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "117dca62",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from typing import Tuple\n",
    "from uuid import UUID\n",
    "\n",
    "from langsmith import RunTree\n",
    "\n",
    "\n",
    "@traceable(run_type=\"chain\")\n",
    "def argument_chain2(\n",
    "    query: str, *, additional_description: str = \"\", run_tree: RunTree\n",
    ") -> Tuple[str, UUID]:\n",
    "    argument = argument_generator(query, additional_description)\n",
    "    criticism = critic(argument)\n",
    "    refined_argument = refiner(query, additional_description, argument, criticism)\n",
    "    return refined_argument, run_tree.id"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "2b339dd8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# We don't need to pass in the `run_tree` when calling the function. It will be injected\n",
    "# by the decorator\n",
    "result, run_id = argument_chain2(\n",
    "    \"Whether sunshine is good for you.\",\n",
    "    additional_description=\"Provide a concise, few sentence argument on why sunshine is good for you.\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "167c8ea3",
   "metadata": {},
   "source": [
    "With the run ID, you can do things like log feedback from a user after the run is completed, or you can create a public link to share. We will do both below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "e45a0845",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from langsmith import Client\n",
    "\n",
    "client = Client()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "cf7b378c",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Feedback(id=UUID('487f90d9-90fb-445c-a800-1bef841e016e'), created_at=datetime.datetime(2023, 10, 26, 17, 46, 7, 955301, tzinfo=datetime.timezone.utc), modified_at=datetime.datetime(2023, 10, 26, 17, 46, 7, 955316, tzinfo=datetime.timezone.utc), run_id=UUID('5941500c-7f00-4081-854d-59bdf358e3ae'), key='user_feedback', score=0.5, value=None, comment=None, correction={'generation': 'Sunshine is nice. Full stop.'}, feedback_source=FeedbackSourceBase(type='api', metadata={}))"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "client.create_feedback(\n",
    "    run_id,\n",
    "    \"user_feedback\",\n",
    "    score=0.5,\n",
    "    correction={\"generation\": \"Sunshine is nice. Full stop.\"},\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1656dd86",
   "metadata": {},
   "source": [
    "[![RunTree 2](./img/snapshot_2.png)](https://smith.langchain.com/public/7e7b6caa-80bc-41af-bed1-35cd1011de77/r)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "adfc2fad",
   "metadata": {},
   "source": [
    "## Configuring traces\n",
    "\n",
    "One way to make your application traces more useful or actionable is to tag or add metadata to the logs. That way you can do things like track the version of your code or deployment environment in a single project.\n",
    "\n",
    "The traceable decorator can be configured to add additional information such as:\n",
    "- string tags\n",
    "- arbitrary key-value metadata\n",
    "- custom trace names\n",
    "- manually-specified run ID\n",
    "\n",
    "Below is an example. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "ac98115b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# You can add tags and metadata (or even the project name) directly in the decorator\n",
    "@traceable(\n",
    "    run_type=\"chain\",\n",
    "    name=\"My Argument Chain\",\n",
    "    tags=[\"tutorial\"],\n",
    "    metadata={\"githash\": \"e38f04c83\"},\n",
    ")\n",
    "def argument_chain_3(query: str, additional_description: str = \"\") -> str:\n",
    "    argument = argument_generator(query, additional_description)\n",
    "    criticism = critic(argument)\n",
    "    return refiner(query, additional_description, argument, criticism)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "354e54d9-5107-4f93-a76e-52dd2f9d2f96",
   "metadata": {},
   "source": [
    "This information can also be added when the function is called. This is done by passing a dictionary to the `langsmith_extra` argument. \n",
    "\n",
    "Below, let's manually add some tags and the UUID for the run. We can then use this UUID in the same way as before."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "217e03ad",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from uuid import uuid4\n",
    "\n",
    "# You can manually specify an ID rather than letting\n",
    "# the decorator generate one for you\n",
    "requested_uuid = uuid4()\n",
    "\n",
    "result = argument_chain_3(\n",
    "    \"Whether sunshine is good for you.\",\n",
    "    additional_description=\"Provide a concise, few sentence argument on why sunshine is good for you.\",\n",
    "    # You can also add tags, metadata, or the run ID directly via arguments to the langsmith_extra argument\n",
    "    # at all-time.\n",
    "    langsmith_extra={\n",
    "        \"tags\": [\"another-tag\"],\n",
    "        \"metadata\": {\"another-key\": 1},\n",
    "        \"run_id\": requested_uuid,\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "de84533a",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Feedback(id=UUID('5451225e-9ca8-473f-b774-d571b6f0f15b'), created_at=datetime.datetime(2023, 10, 26, 17, 47, 2, 163360, tzinfo=datetime.timezone.utc), modified_at=datetime.datetime(2023, 10, 26, 17, 47, 2, 163366, tzinfo=datetime.timezone.utc), run_id=UUID('67838724-6b14-4648-bb7a-3def0684dcdd'), key='user_feedback', score=1, value=None, comment=None, correction=None, feedback_source=FeedbackSourceBase(type='api', metadata={'origin': 'example notebook'}))"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# We can log feedback for the run directly since we've controlled the ID it's assuming\n",
    "client.create_feedback(\n",
    "    requested_uuid, \"user_feedback\", score=1, source_info={\"origin\": \"example notebook\"}\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0b955cab",
   "metadata": {},
   "source": [
    "Now you can navigate to the run with the requested UUID to see the simulated \"user feedback\".\n",
    "\n",
    "[![Tagged Run Tree](./img/snapshot_3.png)](https://dev.smith.langchain.com/public/502a9bc4-44b1-4e86-bb19-3d6b9766f248/r)\n",
    "\n",
    "Clicking in to the 'Metadata' tab, you can see the metadata has been stored for the trace.\n",
    "\n",
    "[![Run Tree Metadata](./img/snapshot_3_metadata.png)](https://dev.smith.langchain.com/public/502a9bc4-44b1-4e86-bb19-3d6b9766f248/r?tab=2)\n",
    "\n",
    "Once you've stored these tagged runs, you can filter and search right in the web app by clicking on the suggested filters or by writing out the query in the search bar:\n",
    "\n",
    "\n",
    "![Filtering Tags](./img/snapshot_3_tag_filter.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d212bffc-9798-43af-8dd7-d3c5fbf72582",
   "metadata": {},
   "source": [
    "## Recap\n",
    "\n",
    "In this walkthrough, you made an example LLM application and instrumented it using the `@traceable` decorator from the LangSmith SDK.\n",
    "\n",
    "You also added tags and metadata and even logged feedback to the runs. The traceable decorator is a light-weight and flexible way to start debugging and monitoring your application."
   ]
  }
 ],
 "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}