https://github.com/sbslee/streamlit-openai
Build AI chatbots with Streamlit and OpenAI's API
https://github.com/sbslee/streamlit-openai
assistants-api chat-completions-api function-calling openai streamlit
Last synced: 8 months ago
JSON representation
Build AI chatbots with Streamlit and OpenAI's API
- Host: GitHub
- URL: https://github.com/sbslee/streamlit-openai
- Owner: sbslee
- License: mit
- Created: 2025-02-04T03:33:12.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-09T12:33:50.000Z (over 1 year ago)
- Last Synced: 2025-02-13T01:35:29.898Z (over 1 year ago)
- Topics: assistants-api, chat-completions-api, function-calling, openai, streamlit
- Language: Python
- Homepage:
- Size: 49.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://badge.fury.io/py/streamlit-openai)
Welcome to the `streamlit-openai` package!
This package provides a Streamlit component for building interactive chat
interfaces powered by OpenAI.
Here’s a quick overview of the package’s key features:
- Easily create chat interfaces in Streamlit
- Real-time streaming responses using the Responses API
- Integration with OpenAI tools: reasoning, function calling, remote MCP, file search, code interpreter, vision, image generation, web search, and more
- File input support for richer interactions
- Fully customizable chat interface, including model selection, temperature settings, and more
- Support for saving and retrieving chat history
# Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Schematic Diagram](#schematic-diagram)
- [Features](#features)
- [Function Calling](#function-calling)
- [Image Generation Example](#image-generation-example)
- [Web Search Example](#web-search-example)
- [Audio Transcription Example](#audio-transcription-example)
- [Reasoning](#reasoning)
- [Remote MCP](#remote-mcp)
- [File Inputs](#file-inputs)
- [Message Attachments](#message-attachments)
- [Static File Upload](#static-file-upload)
- [File Uploader Widget](#file-uploader-widget)
- [Vision](#vision)
- [Image Generation](#image-generation)
- [File Search](#file-search)
- [PDF Vision Support](#pdf-vision-support)
- [Vector Store Retrieval](#vector-store-retrieval)
- [Web Search](#web-search)
- [Code Interpreter](#code-interpreter)
- [Chat History](#chat-history)
- [Chat Summary](#chat-summary)
- [Token Usage](#token-usage)
- [Storage Management](#storage-management)
- [Customization](#customization)
- [Model Selection](#model-selection)
- [Temperature](#temperature)
- [Instructions](#instructions)
- [Avatar Image](#avatar-image)
- [Welcome Message](#welcome-message)
- [Example Messages](#example-messages)
- [Info Message](#info-message)
- [Input Box Placeholder](#input-box-placeholder)
- [Chat Completions and Assistants APIs](#chat-completions-and-assistants-apis)
- [Changelog](#changelog)
# Installation
```sh
$ pip install streamlit-openai streamlit openai
```
# Usage
Export your OpenAI API key:
```sh
$ export OPENAI_API_KEY='sk-...'
```
Save the following code to `app.py`:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat()
st.session_state.chat.run()
```
Run the app:
```sh
$ streamlit run app.py
```
# Schematic Diagram
The diagram below illustrates the `Section` and `Block` classes used
to create a chat interface.
In the diagram, the uploaded file (`instructions.txt`) contains the following
content:
"Create a 2x10 table with random numbers and save it as a CSV file, using 'X'
and 'Y' as column names. Then, generate a scatter plot based on this table.
Save the plot as a PNG file. Finally, display both the plot and the table."
The assistant uses file search to retrieve the instructions from the uploaded
file, and the code interpreter to execute the instructions and generate the
output files.
# Features
## Function Calling
You can define and invoke custom functions within a chat using OpenAI's
function calling capabilities. To create a custom function, provide the
`name`, `description`, `parameters`, and `handler` arguments when initializing
a `CustomFunction`.
### Image Generation Example
Update: As of the 0.1.2 release, the `streamlit_openai` package natively
supports image generation (see [Image Generation](#image-generation))
Therefore, creating a custom function for this purpose is no longer necessary.
However, if you prefer to define a custom image generation function, you can
still do so using the `CustomFunction` class.
Below is an example of a custom function that generates an image based on a
user-provided prompt:
```python
import streamlit as st
import openai
import streamlit_openai
if "chat" not in st.session_state:
def handler(prompt):
client = openai.OpenAI()
response = client.images.generate(
model="dall-e-3",
prompt=prompt,
size="1024x1024",
quality="standard",
n=1,
)
return response.data[0].url
generate_image = streamlit_openai.CustomFunction(
name="generate_image",
description="Generate an image based on a given prompt.",
parameters={
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "A description of the image to be generated.",
}
},
"required": ["prompt"]
},
handler=handler
)
st.session_state.chat = streamlit_openai.Chat(
functions=[generate_image]
)
st.session_state.chat.run()
```
### Web Search Example
Update: As of the 0.1.2 release, the `streamlit_openai` package natively
supports web search (see [Web Search](#web-search)). Therefore, creating a
custom function for this purpose is no longer necessary. However, if you
prefer to define a custom web search function, you can still do so using the
`CustomFunction` class.
You can create a custom function to search the web using a given query. Below
is an example:
```python
import streamlit as st
import openai
import streamlit_openai
if "chat" not in st.session_state:
def handler(prompt):
client = openai.OpenAI()
response = client.chat.completions.create(
model="gpt-4o-search-preview",
web_search_options={},
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content
search_web = streamlit_openai.CustomFunction(
name="search_web",
description="Search the web using a query.",
parameters={
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "Search query.",
}
},
"required": ["prompt"]
},
handler=handler
)
st.session_state.chat = streamlit_openai.Chat(
functions=[search_web],
)
st.session_state.chat.run()
```
### Audio Transcription Example
You can create a custom function to transcribe audio files. Below is an
example:
```python
import streamlit as st
import openai
import streamlit_openai
if "chat" not in st.session_state:
def handler(audio_file):
client = openai.OpenAI()
response = client.audio.transcriptions.create(
model="gpt-4o-transcribe",
file=open(audio_file, "rb"),
)
return response.text
transcribe_audio = streamlit_openai.CustomFunction(
name="transcribe_audio",
description="Convert speech to text.",
parameters={
"type": "object",
"properties": {
"audio_file": {
"type": "string",
"description": "The audio file to transcribe.",
}
},
"required": ["audio_file"]
},
handler=handler
)
st.session_state.chat = streamlit_openai.Chat(
functions=[transcribe_audio],
)
st.session_state.chat.run()
```
## Reasoning
The `Chat` class supports OpenAI's reasoning capabilities, allowing the
assistant to perform complex reasoning tasks. To enable reasoning, select a
reasoning model when initializing the `Chat` class (e.g., `model="o3"`).
Depending on the selected model, you may need to disable some features that
are not compatible with reasoning. For example, web search is not supported
with reasoning models, so you should set `allow_web_search=False` when
initializing the `Chat` class.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
model="o3", # Select a reasoning model
allow_web_search=False, # Disable web search
)
st.session_state.chat.run()
```
## Remote MCP
The `Chat` class supports OpenAI's remote MCP (Model Context Protocol) for
performing various tasks. To create a remote MCP, provide the required
parameters -- `server_label` and `server_url` -- when initializing a
`RemoteMCP`. Depending on your use case, you may also need to specify
additional parameters such as `require_approval`, `headers`, and
`allowed_tools`.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
deepwiki = streamlit_openai.RemoteMCP(
server_label="deepwiki",
server_url="https://mcp.deepwiki.com/mcp",
)
st.session_state.chat = streamlit_openai.Chat(
mcps=[deepwiki]
)
st.session_state.chat.run()
```
## File Inputs
You can provide file inputs to the chat interface, allowing the assistant
to access and utilize the content of the files during the conversation.
### Message Attachments
You can upload files in the chat by clicking the attachment icon or dragging
them into the input box. Uploaded files are sent along with your message, and
the assistant can access their content. This behavior is controlled by the
`accept_file` parameter when initializing the `Chat` class. Below is an
example of how to enable file uploads in the chat interface:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
accept_file="multiple" # Allow multiple file uploads (default)
# accept_file=True, # Allow only one file upload
# accept_file=False, # Disable file uploads entirely
)
st.session_state.chat.run()
```
### Static File Upload
You can upload files statically by providing the `uploaded_files` parameter
when initializing the `Chat` class. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
uploaded_files=["example.pdf"]
)
st.session_state.chat.run()
```
### File Uploader Widget
You can use `st.file_uploader` to allow users to upload files dynamically.
Note that while the widget supports file removal, the files will still remain
in the chat context. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat()
uploaded_files = st.sidebar.file_uploader("Upload Files", accept_multiple_files=True)
st.session_state.chat.run(uploaded_files=uploaded_files)
```
## Vision
The `Chat` class supports OpenAI’s vision capabilities, allowing image input
to be processed within a chat.
Currently, the following image formats are supported: `.png`, `.jpeg`, `.jpg`,
`.webp`, and `.gif`.
Here’s an example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
uploaded_files=["example.jpeg"]
)
st.session_state.chat.run()
```
## Image Generation
The `Chat` class supports OpenAI's image generation capabilities, allowing the
assistant to generate images based on user prompts. By default, this feature is
enabled, but you can disable it by setting `allow_image_generation=False` when
initializing the `Chat` class. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
allow_image_generation=True, # Enable image generation (default)
# allow_image_generation=False, # Disable it
)
st.session_state.chat.run()
```
## File Search
The `Chat` class supports file search capabilities, enabling the assistant to
search through uploaded files and retrieve relevant information during a
conversation. To disable it, set `allow_file_search=False` when initializing
`Chat`.
The following file formats are currently supported: `.c`, `.cpp`, `.cs`,
`.css`, `.doc`, `.docx`, `.go`, `.html`, `.java`, `.js`, `.json`, `.md`,
`.pdf`, `.php`, `.pptx`, `.py`, `.rb`, `.sh`, `.tex`, `.ts`, and `.txt`.
It's notewordthy that the file search feature doesn't support image
processing, except for PDFs, which can be processed using OpenAI's vision.
See [PDF Vision Support](#pdf-vision-support) for more details.
When the user uploads one or more files, a new vector store is created, and
the files are indexed for search. If additional files are uploaded later, the
existing vector store is updated with the new files.
Note that OpenAI's file search currently supports a maximum of two vector
stores in use simultaneously. See
[Vector Store Retrieval](#vector-store-retrieval) for more details.
Below is an example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
allow_file_search=True, # Enable file search (default)
# allow_file_search=False # Disable it
uploaded_files=["example.docx"]
)
st.session_state.chat.run()
```
### PDF Vision Support
File search retrieves information from a knowledge base using semantic and
keyword search. However, it does not support processing images within files
-- except in the case of PDFs. PDF files can be processed using OpenAI's
vision capabilities, allowing the assistant to extract both text and images
from each page. Notably, PDFs processed this way do not trigger the creation
of a vector store, as they are handled through the vision model instead.
There is a limitation, however: you can upload up to 100 pages and a total of
32MB of content in a single PDF upload. If the uploaded PDF exceeds this
limit, the assistant will fall back to standard file search, which indexes
only the text content of the PDF.
### Vector Store Retrieval
If you already have existing vector stores created using the OpenAI API, you
can use them in the chat interface. This is particularly useful for retrieving
relevant information from previously indexed files without needing to
re-upload them -- especially if the files are large or numerous.
To use existing vector stores in a chat, provide their IDs when initializing
the `Chat` class. This enables the system to search and retrieve relevant
information from those stores.
Note that OpenAI's file search currently supports a maximum of two vector
stores at a time, meaning you can provide up to two vector store IDs. However,
if you specify two vector store IDs, you won’t be able to upload new files.
This is by design -- existing vector stores are not updated because they are
presumably important and shared across applications, and modifying them could
lead to unintended issues.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
vector_store_ids=["vs_...", "vs_..."]
)
st.session_state.chat.run()
```
## Web Search
By default, the `Chat` class supports OpenAI's web search capability,
allowing the assistant to retrieve up-to-date information from the web.
To disable this feature, set `allow_web_search=False` when initializing
the `Chat` class. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
allow_web_search=True # Enable web search (default)
# allow_web_search=False # Disable it
)
st.session_state.chat.run()
```
## Code Interpreter
By default, the `Chat` class runs Python code in a sandboxed environment using
OpenAI's code interpreter. It can read, write, and analyze files in formats
like text, CSV, and images. To disable this, set
`allow_code_interpreter=False` when initializing `Chat`.
The following file formats are currently supported: `.c`, `.cs`, `.cpp`,
`.csv`, `.doc`, `.docx`, `.html`, `.java`, `.json`, `.md`, `.pdf`, `.php`,
`.pptx`, `.py`, `.rb`, `.tex`, `.txt`, `.css`, `.js`, `.sh`, `.ts`, `.csv`,
`.jpeg`, `.jpg`, `.gif`, `.pkl`, `.png`, `.tar`, `.xlsx`, `.xml`, and `.zip`.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
allow_code_interpreter=True # Enable code interpreter (default)
# allow_code_interpreter=False # Disable it
)
st.session_state.chat.run()
```
## Chat History
You can save chat history to let users resume conversations across sessions.
Use the `Chat` class’s `save` method to save history as a ZIP file. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat()
with st.sidebar:
if st.button("Save"):
st.session_state.chat.save("history.zip")
st.session_state.chat.run()
```
After saving the chat history, you can load it in a new session by passing
the file path to the `Chat.load` method:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat.load("history.zip")
st.session_state.chat.run()
```
## Chat Summary
The `Chat` class automatically generates a summary of the chat history,
accessible via the `Chat.summary` property. This summary is created using
OpenAI's Chat Completions API and provides a concise overview of the
conversation. Note that when a new chat is started, the default summary is
`"New Chat"`. When there is enough context in the chat history, the summary
will be automatically generated. Once the summary is generated, it will not
change.
## Token Usage
The `Chat` class offers the `Chat.input_tokens` and `Chat.output_tokens`
properties to monitor token usage during a chat session. These properties
return the number of input and output tokens used, respectively. This feature
is particularly useful for tracking token consumption and managing costs when
utilizing OpenAI's API.
## Storage Management
You can delete all vector stores, files, and containers associated with the
exported API key using the command-line interface:
```sh
$ streamlit-openai -h
usage: streamlit-openai [-h] [-v] [--keep ID [ID ...]] {delete-all,delete-files,delete-vector-stores,delete-containers}
CLI tool to delete OpenAI files, vector stores, and containers.
positional arguments:
{delete-all,delete-files,delete-vector-stores,delete-containers}
command to execute
options:
-h, --help show this help message and exit
-v, --version show the version of the tool
--keep ID [ID ...] list of IDs to keep (e.g., file-123, vs_456, cntr_789)
```
# Customization
## Model Selection
The default model used by the assistant in the chat interface is `gpt-4o`. You
can customize the model used by the assistant by providing the `model`
parameter. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(model="o3-mini")
st.session_state.chat.run()
```
## Temperature
You can customize the temperature used by the assistant in the chat interface
by providing the `temperature` parameter. The temperature controls the
randomness of the assistantant's responses. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(temperature=0.5)
st.session_state.chat.run()
```
## Instructions
You can customize the instructions provided to the assistant in the chat
interface by providing the `instructions` parameter. The instructions provide
context for the assistant and can help guide its responses. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
instructions="You are a helpful assistant."
)
st.session_state.chat.run()
```
## Avatar Image
You can customize the avatar images for the assistant and user in the chat
interface by providing the `assistant_avatar` and `user_avatar` parameters.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(assistant_avatar="🦖")
st.session_state.chat.run()
```
## Welcome Message
You can customize the welcome message displayed in the chat interface by
providing the `welcome_message` parameter.
Note that if a chat history is provided, the welcom message will not be
displayed, as the chat history takes precedence.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
welcome_message="Hello! How can I assist you today?"
)
st.session_state.chat.run()
```
## Example Messages
You can use the `example_messages` parameter to provide example messages in
the chat interface, helping users understand how to interact with the
assistant.
Note that if a chat history is provided, the example messages will not be
displayed, as the chat history takes precedence.
Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
example_messages=[
"Can you tell me a joke?",
"What is the capital of France?",
"How do you make a paper airplane?",
"What is the weather like today?",
],
)
st.session_state.chat.run()
```
## Info Message
The `info_message` parameter displays a persistent message at the top of the
chat, guiding users on how to interact with the assistant. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
info_message="Don't share sensitive info. AI may be inaccurate."
)
st.session_state.chat.run()
```
## Input Box Placeholder
You can set custom placeholder text for the chat input box using the
`placeholder` parameter when initializing the `Chat` class. Example:
```python
import streamlit as st
import streamlit_openai
if "chat" not in st.session_state:
st.session_state.chat = streamlit_openai.Chat(
placeholder="Type your message here..."
)
st.session_state.chat.run()
```
# Chat Completions and Assistants APIs
Before the 0.1.0 release, the `streamlit-openai` package supported the OpenAI
Chat Completions and Assistants APIs. However, the Responses API is now
OpenAI's most advanced interface for generating model outputs, and the
Assistants API is scheduled for deprecation in early 2026. While the Chat
Completions API will remain available, OpenAI recommends using the Responses
API for all new applications, as it offers a more powerful and flexible way
to interact with their models. Starting with the 0.1.0 release, the package
has been updated to use the Responses API exclusively.
# Changelog
For a detailed list of changes, please refer to the [CHANGELOG](CHANGELOG.md).