Using the OpenAI Assistant in a Jupyter Notebook with PyCharm

Nikita Melashchenko · (18 November 2023) · guide

This guide will walk you through how to use a Jupyter notebook that leverages the OpenAI API to communicate with OpenAI Assistants within PyCharm. This notebook allows you to interact with an AI assistant, which can answer questions, provide explanations and generate code in accordance with custom instructions and uploaded documents, by sending messages and retrieving a history of a conversation.

This guide was prepared for users such as students, researchers and academics without a technical background. It is intended to be a step-by-step tutorial that covers the entire process from cloning the project to running the notebook.

Prerequisites

Before you start, make sure you have the following:

A computer with an internet connection.
Basic knowledge of how to use a terminal.
Basic knowledge of how to use a Jupyter notebook.
Python installed on your machine. If you don’t have Python installed, you can download it from the official website.
PyCharm installed on your machine. If you don’t have PyCharm installed, you can download it from the official website.

⚠️ Note: There is a free community version of PyCharm. Educators and students may also request a license to use the professional version free of charge.

Getting started

Step 1: Clone the GitHub Repository

In this step, you will clone the GitHub repository that contains the Jupyter notebook and other necessary files for the project. Cloning a repository means making a copy of it on your local machine. This allows you to work on the project locally.

Here are the detailed steps:

Start by launching PyCharm on your machine.
In the PyCharm interface, navigate to the File menu at the top left corner. From the dropdown, select New Project from Version Control. This option allows you to create a new project in PyCharm by cloning a repository from a version control system like Git.
In the Version Control dropdown, select Git.
In the URL field, enter the URL of the GitHub repository: https://github.com/dv0zn3r/jupyter-openAI-assistant/tree/feature.
In the Directory field, choose the directory on your local machine where you want to clone the repository. This is where the copy of the project will be stored on your computer.
Click Clone to start the cloning process. PyCharm will then download a copy of the repository to your chosen directory.

After completing these steps, you should have a local copy of the repository on your machine, stored in the directory you specified. You can now navigate to this directory in PyCharm and start working on the project. The Jupyter notebook and other files from the repository should be visible in the PyCharm project explorer.

Step 2: Set up a Virtual Environment

In this step, you will set up a virtual environment for the project. A virtual environment is a self-contained Python environment that allows you to install packages without affecting the rest of your system. This is useful because it allows you to install packages for a specific project without worrying about conflicts with other projects or your system’s Python installation.

Here are the detailed steps:

Navigate to the modules.py file in the PyCharm project explorer. This file should be in the root directory of the project.
You should see the message No Python interpreter configured for the project. This is a reminder that you need to set up a virtual environment for the project.
Click on the message to open the Add Python Interpreter window. This window allows you to create a new virtual environment for the project.
In the Add Python Interpreter window, click on the New environment using dropdown and select Virtualenv. This will create a new virtual environment for the project.
Choose the version of Python to use for the virtual environment. You can choose any version of Python that is installed on your machine.
Click OK to create the virtual environment. PyCharm will then create a new virtual environment for the project.

After completing these steps, you should have a virtual environment set up for the project. You can now install packages in this virtual environment without affecting the rest of your system.

Step 3: Install the Required Packages

In this step, you will install the required Python packages for the project. These packages are listed in the requirements.txt file in the repository.

Here are the detailed steps:

Navigate to the requirements.txt file in the PyCharm project explorer. This file should be in the root directory of the project.
At the top of the file, you should see a message that says Install the required packages by running: pip install -r requirements.txt. This is a reminder that you need to install the packages before you can run the project.
Click on the message to open the Install requirements window. This window allows you to install the required packages for the project.
Navigate to the OpenAI-Assistant-Template.ipynb file in the PyCharm project explorer. This file should be in the root directory of the project.
Check whether there is a message Jupyter is not installed. If so, click on the message to install Jupyter.

After completing these steps, you should have all the required packages installed on your machine. Now you have all the tools you need to run the project.

Step 4: Set up an OpenAI Assistant

In this step, you will set up an OpenAI Assistant for the project. An OpenAI Assistant is an AI-powered chatbot that can answer questions, provide explanations and generate code in accordance with custom instructions and uploaded documents.

Here are the detailed steps:

Navigate to platform.openai.com and create an account or log in.
Navigate to the Assistants tab on the left sidebar.
Click on the Create button.
Enter the name of the assistant, for example Research Assistant.
Enter the instructions for the assistant. These instructions tell the assistant how to behave and what kind of responses to provide.
Choose the model for the assistant. GPT-4o mini is recommended as it provides good quality responses at a lower cost.
Toggle on Code Interpreter and/or Retrieval if you want to use these features. Code Interpreter allows the assistant to run code, while Retrieval allows it to search through uploaded documents.
Upload files for the assistant if you want the assistant to use the contents of the files for code interpretation and/or retrieval.
Click on the Save button.
Note the id of the assistant somewhere. It will be displayed at the top of the assistant’s page and looks something like asst_abc123def456. You will need it later.

⚠️ Note: The choice of model affects both the quality and cost of responses. GPT-4o mini is recommended for most use cases as it balances quality and affordability.

After completing these steps, you should have an OpenAI Assistant set up for the project. You can now use the assistant to answer questions, provide explanations and generate code — for now only via the web interface.

Step 5: Obtain an OpenAI API Key

In this step, you will obtain an OpenAI API key for the project. An API key is a unique identifier that allows the notebook to communicate with OpenAI’s servers on your behalf.

Here are the detailed steps:

Navigate to platform.openai.com and log in to your account.
Navigate to the API keys tab on the left sidebar.
Click on the Create new secret key button.
Enter a name for the API key, for example Jupyter Notebook Key.
Click on the Create secret key button.
Copy the key and save it somewhere safe. You will need it later.

⚠️ Note: You will not be able to see this key again after you close the window. Store it in a safe place. OpenAI API usage is billed based on the number of tokens processed. Monitor your usage at platform.openai.com to avoid unexpected charges.

After completing these steps, you should have an OpenAI API key that you will use to authenticate the notebook with the OpenAI API.

Step 6: Set up the Environment Variables

In this step, you will set up the environment variables for the project. Environment variables are variables that are set in the environment and can be accessed by programs running in that environment. They are useful for storing sensitive information like API keys and passwords.

Here are the detailed steps:

Navigate to the example.env file in the PyCharm project explorer. This file should be in the root directory of the project.
Rename the file to .env. This will make the file visible to the project.
In the .env file, you should see the OPENAI_API_KEY variable. Replace the placeholder value with the OpenAI API key that you obtained in the previous step.
Navigate to the OpenAI-Assistant-Template.ipynb file in the PyCharm project explorer. This file should be in the root directory of the project.
In the OpenAI-Assistant-Template.ipynb file, you should see the assistant_id_to_use variable. Replace the placeholder value with the Assistant ID that you noted in Step 4.

⚠️ Note: Make sure get_premade_assistant is set to True. Otherwise, the notebook will set up an assistant for you. In such a case, you will need to set up the model in modules.py file and provide name, description, instructions and tools in OpenAI-Assistant-Template.ipynb.

Optional: If you have previously used an OpenAI Assistant and have a thread id you want to continue, you can replace the thread_id_to_use variable with the id of the thread you want to continue.

⚠️ Note: Make sure start_new_thread is set to False. Otherwise, the notebook will start a new thread for you.

Change the content variable and input the message that you want to send to the assistant.

⚠️ Note: You don’t have to send the message to the assistant. If you just want to retrieve the history of the conversation, skip this cell and run the next one.

After completing these steps, you should have the environment variables set up for the project. You can now use these variables to access the OpenAI API and the OpenAI Assistant.

Step 7: Run the Notebook

In this step, you will run the notebook to interact with the OpenAI Assistant. The notebook allows you to send messages to the assistant and retrieve the assistant’s responses. You can use this to have a conversation with the assistant, or to retrieve the assistant’s responses for archival purposes.

Here are the detailed steps:

Navigate to the OpenAI-Assistant-Template.ipynb file in the PyCharm project explorer. This file should be in the root directory of the project.
Option 1: Run the notebook by clicking on the Run all cells button at the top of the notebook. This will run all the cells in the notebook, sending your message to the assistant and retrieving the assistant’s response.
Option 2: Run each cell separately by clicking the Run selected cell and go to cell below button, excluding the one that sends the message to the assistant. This will allow you to retrieve the assistant’s response without sending a message.
After running the notebook, you should see the assistant’s response displayed in the notebook.

⚠️ Note: You need to run the cells with the initial setup only once. After that you can run the cells with the message and the cells that retrieve the assistant’s response as many times as you want.

You can continue the conversation with the assistant by repeating steps 2 and 3. Each time you run the cells, you’ll see the assistant’s response.

After completing these steps, you should have a working conversation with the OpenAI Assistant through the Jupyter notebook.

Final notes

The repo jupyter-OpenAI-assistant is a fork of OpenAI-Assistants-Template. It was adapted to avoid truncation of the retrieved conversation with the assistant.

The repo jupyter-OpenAI-assistant may encounter an issue with the import of IPython due to a frozen modules issue. Running Python with the -Xfrozen_modules=off flag resolves the import issues. To do this, navigate to the terminal in PyCharm and run:

python -Xfrozen_modules=off -m ipykernel_launcher

Conclusion

That’s it! You now know how to use the OpenAI Assistant in a Jupyter notebook within PyCharm. This tool can be a great way to get and track answers to questions and generate code, which makes it a valuable research tool.

Also see

My Research Workflow with OpenAI Assistants

Using the OpenAI Assistant as a Telegram Bot