examples/quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quickstart\n",
    "\n",
    "This quickstart shows how enact can be used to implement a ChatGPT-style\n",
    "application, which can rewind the conversation to an earlier state and explore\n",
    "different conversation paths.\n",
    "\n",
    "## Prerequisites\n",
    "\n",
    "This notebook requires an OpenAI API key. The notebook will look for the key\n",
    "in the environment variable `OPENAI_API_KEY` and the file `~/openai.key`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Note: you may need to restart the kernel to use updated packages.\n",
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install -q enact\n",
    "%pip install -q openai"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Checking /home/leo/openai.key for api key\n",
      "Found api key at /home/leo/openai.key\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "\n",
    "api_key: str = None\n",
    "\n",
    "if 'OPENAI_API_KEY' in os.environ:\n",
    "  print('Using OpenAI API key from environment variable.')\n",
    "  api_key = os.environ['OPENAI_API_KEY']\n",
    "else:\n",
    "  path = os.path.join(os.path.expanduser('~'), 'openai.key')\n",
    "  print(f'Checking {path} for api key')\n",
    "  if os.path.exists(path):\n",
    "    print(f'Found api key at {path}')\n",
    "    api_key = open(path).read().strip()\n",
    "\n",
    "assert api_key, 'Please provide API key.'\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Assistant Chat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "import enact\n",
    "import openai  # type: ignore\n",
    "\n",
    "openai.api_key = api_key"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will first define two enact resources to represent messages\n",
    "and conversations:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List\n",
    "import dataclasses\n",
    "\n",
    "@enact.register\n",
    "@dataclasses.dataclass\n",
    "class Message(enact.Resource):\n",
    "  role: str  # \"system\", \"assistant\" or \"user\"\n",
    "  content: str\n",
    "\n",
    "@enact.register\n",
    "@dataclasses.dataclass\n",
    "class Conversation(enact.Resource):\n",
    "  messages: List[Message]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we define an `Invokable` resource that calls the GPT API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Message(role='assistant', content='Hi there! How can I assist you today?')"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "@enact.typed_invokable(\n",
    "  input_type=Conversation,\n",
    "  output_type=Message)\n",
    "class GPT(enact.Invokable[Conversation, Message]):\n",
    "  def call(self, conversation: Conversation) -> Message:\n",
    "    response = openai.ChatCompletion.create(\n",
    "      model='gpt-3.5-turbo',\n",
    "      messages=[c.to_resource_dict() for c in conversation.messages])\n",
    "    return Message.from_fields(response['choices'][0]['message'])\n",
    "\n",
    "gpt = GPT()\n",
    "gpt(Conversation(messages=[Message(role='user', content='Hello!')]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we define a 'program' that represents the conversation between a user and\n",
    "an assistant. This is just a loop that alternates between querying the user and\n",
    "GPT.\n",
    "\n",
    "The invokable takes no input (hence `enact.NoneResource`) and returns a\n",
    "conversation when a user types 'exit'."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "@enact.typed_invokable(enact.NoneResource, Conversation)\n",
    "@dataclasses.dataclass\n",
    "class UserConversation(\n",
    "    enact.Invokable[enact.NoneResource, Conversation]):\n",
    "  \"\"\"A conversation with a user.\"\"\"\n",
    "  assistant: enact.Invokable[Conversation, Message] = dataclasses.field(\n",
    "    default_factory=GPT)\n",
    "\n",
    "  def call(self) -> Conversation:\n",
    "    conversation = Conversation(messages=[])\n",
    "    # A conversation is a loop of user messages and assistant messages.\n",
    "    while True:\n",
    "      # Sample user message.\n",
    "      user_content = enact.request_input(\n",
    "        requested_type=enact.Str, for_resource=conversation)\n",
    "      if user_content == 'exit':\n",
    "        return conversation\n",
    "\n",
    "      # Append the user message to the conversation.\n",
    "      conversation.messages.append(\n",
    "        Message(role='user', content=str(user_content)))\n",
    "      \n",
    "      # Call the assistant.\n",
    "      assistant_message = self.assistant(conversation)\n",
    "      conversation.messages.append(assistant_message)\n",
    "      "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to resolve user inputs, enact needs to run a managed execution, called\n",
    "an `Invocation`. Invocations are journaled, and need to be performed in the \n",
    "context of an enact `Store` object, which dictates where the generated resources\n",
    "are persisted.\n",
    "\n",
    "When user input is required, enact raises an `InputRequest` exception, and the\n",
    "invocation needs to be continued once it is resolved. The `InvocationGenerator`\n",
    "provides a convenient python generator interface to step through multiple\n",
    "input requests until the execution is complete.\n",
    "\n",
    "To sample user input we will use the python `input` function. This will open\n",
    "an input window in the jupyter notebook environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "user: Do you think \"enact\" is a good name for a generative software framework?\n",
      "assistant: Yes, \"enact\" could be a good name for a generative software framework. It conveys a sense of action, implementation, and bringing ideas to life. It suggests that the framework can be used to enact or create various things. However, the final judgment of a name depends on factors such as brand positioning, target audience, and competition. It's important to consider those aspects and ensure the name aligns with the framework's purpose and goals.\n",
      "user: What else could I call it?\n",
      "assistant: Here are a few alternative name suggestions for a generative software framework:\n",
      "\n",
      "1. \"EvoGen\" (short for Evolutionary Generator)\n",
      "2. \"SynthiCreate\" (combining synthesis and creation)\n",
      "3. \"InfiniForge\" (implies infinite possibilities and forging creation)\n",
      "4. \"GeniSys\" (a play on \"genius\" and \"system\" to signify intelligent generation)\n",
      "5. \"VivoCraft\" (a combination of \"vivo\" meaning life and \"craft\" signifying creation)\n",
      "6. \"MorphoMaker\" (morphogenesis-based framework for generating diverse outputs)\n",
      "7. \"ArtiVolve\" (blending \"artificial\" and \"evolve\" to connote generative evolution)\n",
      "8. \"MetaGen\" (indicating a framework for meta-generative coding)\n",
      "9. \"Futurify\" (communicates a software framework that generates future-oriented outputs)\n",
      "10. \"InspiroForge\" (suggests the framework's ability to inspire and forge creative outputs)\n",
      "\n",
      "Remember, choosing a name involves consideration of branding, marketing, and the target audience, so it's essential to align the name with the specific qualities and goals of your generative software framework.\n"
     ]
    }
   ],
   "source": [
    "import sys\n",
    "\n",
    "store = enact.FileStore(root_dir='store_data')\n",
    "\n",
    "def prompt_user(messages):\n",
    "  \"\"\"Displays the previous message and prompts the user.\"\"\"\n",
    "  for message in messages[-2:]:\n",
    "    print(f'{message.role}: {message.content}')\n",
    "    sys.stdout.flush()\n",
    "  return input()\n",
    "\n",
    "with store:\n",
    "  invocation_generator = enact.InvocationGenerator(UserConversation())\n",
    "  for input_request in invocation_generator:\n",
    "    user_input = prompt_user(input_request.for_resource().messages)\n",
    "    invocation_generator.set_input(enact.Str(user_input))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The invocation is now complete. The full execution record of our\n",
    "`UserConversation` invokable is stored in the invocation object. To\n",
    "illustrate, let's look at the details of one of the tracked calls\n",
    "that happened during execution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Invocation:\n",
      "  request:\n",
      "    -> Request#8865e1:\n",
      "      invokable: -> GPT()#2e772c\n",
      "      input: -> Conversation#b60b3f: messages: [ Message(role='user', content='Do you think \"enact\" is a good name for a generative software framework?')]\n",
      "  response:\n",
      "    -> Response#76d775:\n",
      "      invokable: -> GPT#2e772c\n",
      "      output: -> Message(role='assistant', content='Yes, \"enact\" could be a good name for a generative software framework. It conveys a sense of action, implementation, and bringing ideas to life. It suggests that the framework can be used to enact or create various things. However, the final judgment of a name depends on factors such as brand positioning, target audience, and competition. It\\'s important to consider those aspects and ensure the name aligns with the framework\\'s purpose and goals.')#df1418\n",
      "      raised: None\n",
      "      raised_here: False\n",
      "      children: []\n"
     ]
    }
   ],
   "source": [
    "with store:\n",
    "  invocation = invocation_generator.invocation\n",
    "  enact.pprint(invocation.get_child(1), skip_repeated_refs=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see all execution details, including the specific invokable that was\n",
    "called, the input it received and the output it generated.\n",
    "\n",
    "## Rewinding the state of the conversation\n",
    "\n",
    "Invocations can additionally be rewound and replayed.\n",
    "\n",
    "For example, to regenerate the last answer by GPT and continue the conversation\n",
    "from there, we can simply `rewind` the invocation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "user: What else could I call it?\n",
      "assistant: Here are some alternative suggestions for naming a generative software framework:\n",
      "\n",
      "1. \"GenerateX\"\n",
      "2. \"Genesis\"\n",
      "3. \"CreateVue\"\n",
      "4. \"CreaGen\"\n",
      "5. \"InnovatePro\"\n",
      "6. \"GeneraSys\"\n",
      "7. \"IdeaForge\"\n",
      "8. \"ArtiCraft\"\n",
      "9. \"CodeSynth\"\n",
      "10. \"ProtoSpark\"\n",
      "\n",
      "Remember to consider factors such as uniqueness, relevance, and brand positioning while choosing a name. It's also a good idea to check for existing software frameworks or projects with similar names to avoid confusion and trademark issues.\n",
      "user: Those are terrible names!\n",
      "assistant: I apologize if the suggested names did not meet your expectations. Coming up with a perfect name can be subjective and challenging. To provide more suitable alternatives, it would be helpful to understand the specific qualities or attributes you would like the name to convey related to your generative software framework. Could you provide any specific keywords or concepts you would like the name to incorporate?\n"
     ]
    }
   ],
   "source": [
    "with store:\n",
    "  earlier_state = invocation.rewind(2)  # Undo user 'exit' and GPT response.\n",
    "  invocation_generator = enact.InvocationGenerator(\n",
    "    from_invocation=earlier_state)\n",
    "  for input_request in invocation_generator:\n",
    "    user_input = prompt_user(input_request.for_resource().messages)\n",
    "    invocation_generator.set_input(enact.Str(user_input))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can now write a simple text interface that allows us to use the 'rewind'\n",
    "command to return to an earlier conversation state:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "user: Ok, let's play twenty questions. Is it an animal?\n",
      "assistant: Yes, it is an animal.\n",
      "user: Is it larger than a cat?\n",
      "assistant: Yes, it is larger than a cat.\n",
      "user: Is it larger than a horse?\n",
      "assistant: No, it is not larger than a horse.\n",
      "user: Is it a domesticated animal?\n",
      "assistant: Yes, it is a domesticated animal.\n",
      "user: Ok, I give up. Just tell me what animal you thought of\n",
      "assistant: I was thinking of a dog.\n",
      "\n",
      "REWINDING... *whirr*\n",
      "user: Is it a domesticated animal?\n",
      "assistant: Yes, it is a domesticated animal.\n",
      "user: Is it a dog?\n",
      "assistant: Yes, it is a dog. Well done!\n"
     ]
    }
   ],
   "source": [
    "with store:\n",
    "  user_input = ''\n",
    "  invocation_generator = enact.InvocationGenerator(UserConversation())\n",
    "  while user_input != 'exit':\n",
    "    for input_request in invocation_generator:\n",
    "      user_input = prompt_user(input_request.for_resource().messages)\n",
    "      if user_input == 'rewind':\n",
    "        print('\\nREWINDING... *whirr*')\n",
    "        invocation = invocation_generator.invocation\n",
    "        invocation = invocation.rewind(3)\n",
    "        invocation_generator = enact.InvocationGenerator(\n",
    "          from_invocation=invocation)\n",
    "        break\n",
    "      invocation_generator.set_input(enact.Str(user_input)) "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.8.10"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}