{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "16763ed3",
   "metadata": {},
   "source": [
    "# Lemon Agent\n",
    "\n",
    ">[Lemon Agent](https://github.com/felixbrock/lemon-agent) helps you build powerful AI assistants in minutes and automate workflows by allowing for accurate and reliable read and write operations in tools like `Airtable`, `Hubspot`, `Discord`, `Notion`, `Slack` and `Github`.\n",
    "\n",
    "See [full docs here](https://github.com/felixbrock/lemonai-py-client).\n",
    "\n",
    "\n",
    "Most connectors available today are focused on read-only operations, limiting the potential of LLMs. Agents, on the other hand, have a tendency to hallucinate from time to time due to missing context or instructions.\n",
    "\n",
    "With `Lemon AI`, it is possible to give your agents access to well-defined APIs for reliable read and write operations. In addition, `Lemon AI` functions allow you to further reduce the risk of hallucinations by providing a way to statically define workflows that the model can rely on in case of uncertainty."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4881b484-1b97-478f-b206-aec407ceff66",
   "metadata": {},
   "source": [
    "## Quick Start\n",
    "\n",
    "The following quick start demonstrates how to use Lemon AI in combination with Agents to automate workflows that involve interaction with internal tooling."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff91b41a",
   "metadata": {},
   "source": [
    "### 1. Install Lemon AI\n",
    "\n",
    "Requires Python 3.8.1 and above.\n",
    "\n",
    "To use Lemon AI in your Python project run `pip install lemonai`\n",
    "\n",
    "This will install the corresponding Lemon AI client which you can then import into your script.\n",
    "\n",
    "The tool uses Python packages langchain and loguru. In case of any installation errors with Lemon AI, install both packages first and then install the Lemon AI package."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "340ff63d",
   "metadata": {},
   "source": [
    "### 2. Launch the Server\n",
    "\n",
    "The interaction of your agents and all tools provided by Lemon AI is handled by the [Lemon AI Server](https://github.com/felixbrock/lemonai-server). To use Lemon AI you need to run the server on your local machine so the Lemon AI Python client can connect to it."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e845f402",
   "metadata": {},
   "source": [
    "### 3. Use Lemon AI with Langchain"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3ae6a82",
   "metadata": {},
   "source": [
    "Lemon AI automatically solves given tasks by finding the right combination of relevant tools or uses Lemon AI Functions as an alternative. The following example demonstrates how to retrieve a user from Hackernews and write it to a table in Airtable:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "43476a22",
   "metadata": {},
   "source": [
    "#### (Optional) Define your Lemon AI Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb038670",
   "metadata": {},
   "source": [
    "Similar to [OpenAI functions](https://openai.com/blog/function-calling-and-other-api-updates), Lemon AI provides the option to define workflows as reusable functions. These functions can be defined for use cases where it is especially important to move as close as possible to near-deterministic behavior. Specific workflows can be defined in a separate lemonai.json:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e423ebbb",
   "metadata": {},
   "source": [
    "```json\n",
    "[\n",
    "  {\n",
    "    \"name\": \"Hackernews Airtable User Workflow\",\n",
    "    \"description\": \"retrieves user data from Hackernews and appends it to a table in Airtable\",\n",
    "    \"tools\": [\"hackernews-get-user\", \"airtable-append-data\"]\n",
    "  }\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3fdb36ce",
   "metadata": {},
   "source": [
    "Your model will have access to these functions and will prefer them over self-selecting tools to solve a given task. All you have to do is to let the agent know that it should use a given function by including the function name in the prompt."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ebfb8b5d",
   "metadata": {},
   "source": [
    "#### Include Lemon AI in your Langchain project "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "5318715d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from lemonai import execute_workflow\n",
    "from langchain.llms import OpenAI"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9d082cb",
   "metadata": {},
   "source": [
    "#### Load API Keys and Access Tokens\n",
    "\n",
    "To use tools that require authentication, you have to store the corresponding access credentials in your environment in the format \"{tool name}_{authentication string}\" where the authentication string is one of [\"API_KEY\", \"SECRET_KEY\", \"SUBSCRIPTION_KEY\", \"ACCESS_KEY\"] for API keys or [\"ACCESS_TOKEN\", \"SECRET_TOKEN\"] for authentication tokens. Examples are \"OPENAI_API_KEY\", \"BING_SUBSCRIPTION_KEY\", \"AIRTABLE_ACCESS_TOKEN\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "a370d999",
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\" Load all relevant API Keys and Access Tokens into your environment variables \"\"\"\n",
    "os.environ[\"OPENAI_API_KEY\"] = \"*INSERT OPENAI API KEY HERE*\"\n",
    "os.environ[\"AIRTABLE_ACCESS_TOKEN\"] = \"*INSERT AIRTABLE TOKEN HERE*\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38d158e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "hackernews_username = \"*INSERT HACKERNEWS USERNAME HERE*\"\n",
    "airtable_base_id = \"*INSERT BASE ID HERE*\"\n",
    "airtable_table_id = \"*INSERT TABLE ID HERE*\"\n",
    "\n",
    "\"\"\" Define your instruction to be given to your LLM \"\"\"\n",
    "prompt = f\"\"\"Read information from Hackernews for user {hackernews_username} and then write the results to\n",
    "Airtable (baseId: {airtable_base_id}, tableId: {airtable_table_id}). Only write the fields \"username\", \"karma\"\n",
    "and \"created_at_i\". Please make sure that Airtable does NOT automatically convert the field types.\n",
    "\"\"\"\n",
    "\n",
    "\"\"\"\n",
    "Use the Lemon AI execute_workflow wrapper \n",
    "to run your Langchain agent in combination with Lemon AI  \n",
    "\"\"\"\n",
    "model = OpenAI(temperature=0)\n",
    "\n",
    "execute_workflow(llm=model, prompt_string=prompt)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aef3e801",
   "metadata": {},
   "source": [
    "### 4. Gain transparency on your Agent's decision making\n",
    "\n",
    "To gain transparency on how your Agent interacts with Lemon AI tools to solve a given task, all decisions made, tools used and operations performed are written to a local `lemonai.log` file. Every time your LLM agent is interacting with the Lemon AI tool stack a corresponding log entry is created.\n",
    "\n",
    "```log\n",
    "2023-06-26T11:50:27.708785+0100 - b5f91c59-8487-45c2-800a-156eac0c7dae - hackernews-get-user\n",
    "2023-06-26T11:50:39.624035+0100 - b5f91c59-8487-45c2-800a-156eac0c7dae - airtable-append-data\n",
    "2023-06-26T11:58:32.925228+0100 - 5efe603c-9898-4143-b99a-55b50007ed9d - hackernews-get-user\n",
    "2023-06-26T11:58:43.988788+0100 - 5efe603c-9898-4143-b99a-55b50007ed9d - airtable-append-data\n",
    "```\n",
    "\n",
    "By using the [Lemon AI Analytics](https://github.com/felixbrock/lemon-agent/blob/main/apps/analytics/README.md) you can easily gain a better understanding of how frequently and in which order tools are used. As a result, you can identify weak spots in your agent’s decision-making capabilities and move to a more deterministic behavior by defining Lemon AI functions."
   ]
  }
 ],
 "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
