Chat assistant

​

Prerequisites

• A Writer account: You don’t need an account to use Writer Framework, but you’ll need one to use the AI module. Sign up for a free account here.
• Python 3.9.2 or later: Use the installer from python.org.
• pip: This command-line application comes with Python and is used for installing Python packages, including those from Writer.
• A basic understanding of Python: You should be familiar with the basics of the language.
• Your favorite code editor (optional): There’s a code editor built into Writer for editing back-end code, but you can also use Visual Studio Code, Notepad++, Vim, Emacs, or any text editor made for programming if you prefer.

​

Setting up your project

​

Create a Writer app and get its API key

1

Create the app in Writer

Log into Writer. From the Home screen, click on the Build an app button.The Start building menu will appear, presenting options for the types of apps you can create.Select Framework, located under Developer tools. This will create a brand new app based on Writer Framework.

2

Copy your app's API key

On the next screen, titled How to deploy an application, you can get the API key for the app by clicking on the Reveal key button, located under the text Authenticate with an API key. Your complete API key will be displayed, and a “copy” button will appear. Click this button to copy the key; you’ll use it in the next step.

​

Set up your computer and create the app’s project

pip install writer python-dotenv

export WRITER_API_KEY=[your_api_key]

$env:WRITER_API_KEY=[your_api_key]

set WRITER_API_KEY=[your_api_key]

writer create chat-assistant --template=ai-starter

​

Build the UI

writer edit chat-assistant

• The canvas is in the center. It displays the app’s user interface.
• The column on the left contains:
  • The Core toolkit, which contains all the UI components. You define the user interface by dragging components from the Toolkit and placing them on the canvas.
  • The Component tree, which shows the arrangement of the UI components on the canvas. It’s also useful for selecting items on the canvas, especially when it has a lot of UI components.

1

Examine the header

Select the Header component by clicking it — it’s the component at the top, containing the title AI STARTER and a gray area labeled Empty Header.When you click it, you’ll see the properties panel appear on the right side of the page. This lets you view and edit the properties of the selected component.The first property you’ll see in the panel is the Text property, which defines the text that appears as the header’s title. It should contain the value @{my_app.title}. The @{ and } indicate that my_app.title is a variable and that its contents should be the text displayed instead of the literal text “my_app.title”. You’ll set the value of this variable soon.

2

Clear the Section's default title

Select the Section component by clicking it — it’s just below the Header component and contains the title Section Title and a gray area labeled Empty Section.In the properties panel, clear out the value of the Title property. This will remove the Section’s default title.

3

Add a Text component to the Section

Drag a Text component from the Core toolkit panel on the left (it’s under Content, and you may need to scroll down a little to find it) and into the Section. Sections can act as containers for other components.

You can search for a specific component by using the search bar at the top of the Core toolkit panel.

Select the Text component. In the properties panel, set the Text property to provide instructions or context for your chat assistant. Here’s an example: Welcome to the Chat Assistant. Ask me anything!

4

Add a Chatbot component to the Section

The heart of this app is the Chatbot component, a pre-built component that displays the conversation between the LLM and the user and provides a text field where the user can enter prompts.Drag a Chatbot component from the Core toolkit panel (it’s under Content) into the Section, just below the Text box.

​

Add the back-end code

1

Import libraries and load the Writer Framework API key

You should see the following at the start of the file:

import writer as wf
import writer.ai

Replace that code with the following:

import os
import writer as wf
import writer.ai

# Set the API key
wf.api_key = os.getenv("WRITER_API_KEY")

This code imports the libraries that the application will need and then reads your Writer Framework API key in the WRITER_API_KEY environment variable.

2

Create a handler to respond to the user's input

The application needs a function to handle incoming chat messages. Find these comments in the code…

# Welcome to Writer Framework! 
# This template is a starting point for your AI apps.
# More documentation is available at https://dev.writer.com/framework

…and replace them with the following function:

def generate_completion(state, payload):
  print(f"Here's what the user entered: {payload['content']}")
  state["conversation"] += payload
  print(f"Conversation: {state['conversation'].messages}")
  try:
      for index, chunk in enumerate(state["conversation"].stream_complete()):
          print(f"Chunk {index}: {chunk}")
          if not chunk.get("content"):
              chunk["content"] = ""
          state["conversation"] += chunk
          
      print(f"state['conversation']:\n{state['conversation'].messages}")
  except Exception as e:
      print(f"Error during stream_complete: {e}")

The generate_completion() function will be called when the user enters a prompt, which is contained in the payload object. The payload object is added to the conversation object contained in the application’s state, which adds the user’s prompt to the record of the conversation between the user and the LLM.After adding the user’s prompt to the conversational record, generate_completion() calls the conversation object’s stream_complete() method, which generates an LLM completion based on the conversation so far. As its name implies, stream_complete() returns the completion as a stream of text chunks, which are captured and added to the conversation object.

The conversation object in the code above is an instance of Writer’s Conversation class. You can find out more about this class on our Writer AI module page.

Note that generate_completion() completion uses a lot of print() functions for debugging purposes, and you can use them to get a better idea of what’s happening in the function. You’ll see their output in both your terminal application and in the project editor’s ‘log’ pane (which will be covered shortly) as you use the chat assistant. This output will include:

• The prompt the user entered
• The chunks of data that make up the LLM’s response as they are generated
• The record of the conversation between the user and the LLM.

The print() functions don’t affect the operation of the chat assistant in any way, and you can remove them if you wish.

3

Initialize the application

The final step is to set the application’s initial state. Find this code, which should be just after the generate_completion() function…

# Initialise the state
wf.init_state({
    "my_app": {
        "title": "AI STARTER"
    },
})

…and replace it with this:

# Initialize the state
wf.init_state({
    "conversation": writer.ai.Conversation(),
    "my_app": {
        "title": "CHAT ASSISTANT"
    },
})

The Writer Framework’s init_state() method sets the initial value of state, a dictionary containing values that define the state of the application. The key-value pairs in state are how you store values used by your app and how you pass data between the back-end code and the UI.The code above sets the initial value of state so that it has two key-value pairs:

• conversation: An object that keeps a record of the conversation that the user is having with the LLM. You’ll bind its value to the Chatbot component soon.
• my_app: A dictionary containing values that define the application’s appearance. This dictionary has a single key-value pair, title, which defines the text that appears as the application’s title in the Header.

For more details about the state variable, see our Application state page.

4

Save the updated code and hide the code editor

That’s all the code. If you edited the code in the browser, save it by clicking the “save” button near the top right corner of the code editor.Click the “toggle code” button to hide the code editor.

​

Bind the UI to the back-end code

1

Observe that the heading at the top of the app is now 'CHATBOT ASSISTANT'

Earlier, you saw that the Header component’s Text property was set to @{my_app.title}, a value in the app’s state variable. You changed this value when you update the call to the Writer Framework’s init_state() method.

2

Bind the Chatbot component to the 'state' variable's 'conversation' key

Recall that the conversation object contained within the state variable contains the record of the conversation that the user is having with the LLM. Binding the Chatbot component to this object allows it to display the conversation to the user.Select the Chatbot component. In the properties panel, find the Conversation property and set its value to @{conversation}.The value @{conversation} specifies that the Chatbot component should get its information from the value corresponding to the conversation key in the application’s state variable.

3

Specify the Chatbot component's event handler

You need to specify that the Chatbot component should call the generate_completion() function when the user enters a prompt.Do this by scrolling down the properties panel to the Events section until you see a property called wf_chatbot_message. Select generate_completion from its menu.

​

Test the application

​

Run the application locally

writer run chat-assistant

​

Conclusion