{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Chapter 1: Basic Prompt Structure\n",
    "\n",
    "- [Lesson](#lesson)\n",
    "- [Exercises](#exercises)\n",
    "- [Example Playground](#example-playground)\n",
    "\n",
    "## Setup\n",
    "\n",
    "Run the following setup cell to load your API key and establish the `get_completion` helper function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install anthropic\n",
    "\n",
    "# Import python's built-in regular expression library\n",
    "import re\n",
    "import anthropic\n",
    "\n",
    "# Retrieve the API_KEY & MODEL_NAME variables from the IPython store\n",
    "%store -r API_KEY\n",
    "%store -r MODEL_NAME\n",
    "\n",
    "client = anthropic.Anthropic(api_key=API_KEY)\n",
    "\n",
    "def get_completion(prompt: str, system_prompt=\"\"):\n",
    "    message = client.messages.create(\n",
    "        model=MODEL_NAME,\n",
    "        max_tokens=2000,\n",
    "        temperature=0.0,\n",
    "        system=system_prompt,\n",
    "        messages=[\n",
    "          {\"role\": \"user\", \"content\": prompt}\n",
    "        ]\n",
    "    )\n",
    "    return message.content[0].text"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Lesson\n",
    "\n",
    "Anthropic offers two APIs, the legacy [Text Completions API](https://docs.anthropic.com/claude/reference/complete_post) and the current [Messages API](https://docs.anthropic.com/claude/reference/messages_post). For this tutorial, we will be exclusively using the Messages API.\n",
    "\n",
    "At minimum, a call to Claude using the Messages API requires the following parameters:\n",
    "- `model`: the [API model name](https://docs.anthropic.com/claude/docs/models-overview#model-recommendations) of the model that you intend to call\n",
    "\n",
    "- `max_tokens`: the maximum number of tokens to generate before stopping. Note that Claude may stop before reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Furthermore, this is a *hard* stop, meaning that it may cause Claude to stop generating mid-word or mid-sentence.\n",
    "\n",
    "- `messages`: an array of input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the messages parameter, and the model then generates the next `Message` in the conversation.\n",
    "  - Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages (they must alternate, if so). The first message must always use the `user` role.\n",
    "\n",
    "There are also optional parameters, such as:\n",
    "- `system`: the system prompt - more on this below.\n",
    "  \n",
    "- `temperature`: the degree of variability in Claude's response. For these lessons and exercises, we have set `temperature` to 0.\n",
    "\n",
    "For a complete list of all API parameters, visit our [API documentation](https://docs.anthropic.com/claude/reference/messages_post)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Examples\n",
    "\n",
    "Let's take a look at how Claude responds to some correctly-formatted prompts. For each of the following cells, run the cell (`shift+enter`), and Claude's response will appear below the block."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt\n",
    "PROMPT = \"Hi Claude, how are you?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt\n",
    "PROMPT = \"Can you tell me the color of the ocean?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt\n",
    "PROMPT = \"What year was Celine Dion born in?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's take a look at some prompts that do not include the correct Messages API formatting. For these malformatted prompts, the Messages API returns an error.\n",
    "\n",
    "First, we have an example of a Messages API call that lacks `role` and `content` fields in the `messages` array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get Claude's response\n",
    "response = client.messages.create(\n",
    "        model=MODEL_NAME,\n",
    "        max_tokens=2000,\n",
    "        temperature=0.0,\n",
    "        messages=[\n",
    "          {\"Hi Claude, how are you?\"}\n",
    "        ]\n",
    "    )\n",
    "\n",
    "# Print Claude's response\n",
    "print(response[0].text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's a prompt that fails to alternate between the `user` and `assistant` roles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get Claude's response\n",
    "response = client.messages.create(\n",
    "        model=MODEL_NAME,\n",
    "        max_tokens=2000,\n",
    "        temperature=0.0,\n",
    "        messages=[\n",
    "          {\"role\": \"user\", \"content\": \"What year was Celine Dion born in?\"},\n",
    "          {\"role\": \"user\", \"content\": \"Also, can you tell me some other facts about her?\"}\n",
    "        ]\n",
    "    )\n",
    "\n",
    "# Print Claude's response\n",
    "print(response[0].text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`user` and `assistant` messages **MUST alternate**, and messages **MUST start with a `user` turn**. You can have multiple `user` & `assistant` pairs in a prompt (as if simulating a multi-turn conversation). You can also put words into a terminal `assistant` message for Claude to continue from where you left off (more on that in later chapters).\n",
    "\n",
    "#### System Prompts\n",
    "\n",
    "You can also use **system prompts**. A system prompt is a way to **provide context, instructions, and guidelines to Claude** before presenting it with a question or task in the \"User\" turn. \n",
    "\n",
    "Structurally, system prompts exist separately from the list of `user` & `assistant` messages, and thus belong in a separate `system` parameter (take a look at the structure of the `get_completion` helper function in the [Setup](#setup) section of the notebook). \n",
    "\n",
    "Within this tutorial, wherever we might utilize a system prompt, we have provided you a `system` field in your completions function. Should you not want to use a system prompt, simply set the `SYSTEM_PROMPT` variable to an empty string."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### System Prompt Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# System prompt\n",
    "SYSTEM_PROMPT = \"Your answer should always be a series of critical thinking questions that further the conversation (do not provide answers to your questions). Do not actually answer the user question.\"\n",
    "\n",
    "# Prompt\n",
    "PROMPT = \"Why is the sky blue?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT, SYSTEM_PROMPT))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Why use a system prompt? A **well-written system prompt can improve Claude's performance** in a variety of ways, such as increasing Claude's ability to follow rules and instructions. For more information, visit our documentation on [how to use system prompts](https://docs.anthropic.com/claude/docs/how-to-use-system-prompts) with Claude.\n",
    "\n",
    "Now we'll dive into some exercises. If you would like to experiment with the lesson prompts without changing any content above, scroll all the way to the bottom of the lesson notebook to visit the [**Example Playground**](#example-playground)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Exercises\n",
    "- [Exercise 1.1 - Counting to Three](#exercise-11---counting-to-three)\n",
    "- [Exercise 1.2 - System Prompt](#exercise-12---system-prompt)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise 1.1 - Counting to Three\n",
    "Using proper `user` / `assistant` formatting, edit the `PROMPT` below to get Claude to **count to three.** The output will also indicate whether your solution is correct."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt - this is the only field you should change\n",
    "PROMPT = \"[Replace this text]\"\n",
    "\n",
    "# Get Claude's response\n",
    "response = get_completion(PROMPT)\n",
    "\n",
    "# Function to grade exercise correctness\n",
    "def grade_exercise(text):\n",
    "    pattern = re.compile(r'^(?=.*1)(?=.*2)(?=.*3).*$', re.DOTALL)\n",
    "    return bool(pattern.match(text))\n",
    "\n",
    "# Print Claude's response and the corresponding grade\n",
    "print(response)\n",
    "print(\"\\n--------------------------- GRADING ---------------------------\")\n",
    "print(\"This exercise has been correctly solved:\", grade_exercise(response))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "❓ If you want a hint, run the cell below!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from hints import exercise_1_1_hint; print(exercise_1_1_hint)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise 1.2 - System Prompt\n",
    "\n",
    "Modify the `SYSTEM_PROMPT` to make Claude respond like it's a 3 year old child."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# System prompt - this is the only field you should change\n",
    "SYSTEM_PROMPT = \"[Replace this text]\"\n",
    "\n",
    "# Prompt\n",
    "PROMPT = \"How big is the sky?\"\n",
    "\n",
    "# Get Claude's response\n",
    "response = get_completion(PROMPT, SYSTEM_PROMPT)\n",
    "\n",
    "# Function to grade exercise correctness\n",
    "def grade_exercise(text):\n",
    "    return bool(re.search(r\"giggles\", text) or re.search(r\"soo\", text))\n",
    "\n",
    "# Print Claude's response and the corresponding grade\n",
    "print(response)\n",
    "print(\"\\n--------------------------- GRADING ---------------------------\")\n",
    "print(\"This exercise has been correctly solved:\", grade_exercise(response))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "❓ If you want a hint, run the cell below!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from hints import exercise_1_2_hint; print(exercise_1_2_hint)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Congrats!\n",
    "\n",
    "If you've solved all exercises up until this point, you're ready to move to the next chapter. Happy prompting!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Example Playground\n",
    "\n",
    "This is an area for you to experiment freely with the prompt examples shown in this lesson and tweak prompts to see how it may affect Claude's responses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt\n",
    "PROMPT = \"Hi Claude, how are you?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt\n",
    "PROMPT = \"Can you tell me the color of the ocean?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Prompt\n",
    "PROMPT = \"What year was Celine Dion born in?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get Claude's response\n",
    "response = client.messages.create(\n",
    "        model=MODEL_NAME,\n",
    "        max_tokens=2000,\n",
    "        temperature=0.0,\n",
    "        messages=[\n",
    "          {\"Hi Claude, how are you?\"}\n",
    "        ]\n",
    "    )\n",
    "\n",
    "# Print Claude's response\n",
    "print(response[0].text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get Claude's response\n",
    "response = client.messages.create(\n",
    "        model=MODEL_NAME,\n",
    "        max_tokens=2000,\n",
    "        temperature=0.0,\n",
    "        messages=[\n",
    "          {\"role\": \"user\", \"content\": \"What year was Celine Dion born in?\"},\n",
    "          {\"role\": \"user\", \"content\": \"Also, can you tell me some other facts about her?\"}\n",
    "        ]\n",
    "    )\n",
    "\n",
    "# Print Claude's response\n",
    "print(response[0].text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# System prompt\n",
    "SYSTEM_PROMPT = \"Your answer should always be a series of critical thinking questions that further the conversation (do not provide answers to your questions). Do not actually answer the user question.\"\n",
    "\n",
    "# Prompt\n",
    "PROMPT = \"Why is the sky blue?\"\n",
    "\n",
    "# Print Claude's response\n",
    "print(get_completion(PROMPT, SYSTEM_PROMPT))"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}