Build a RAG command line chatbot (Python)
This tutorial demonstrates how to build a command line chatbot. The chatbot uses data from your Astra collection for retrieval-augmented generation (RAG) with OpenAI.
This example uses the collection of book summaries from the quickstart, but you can use any collection of documents that have the $vectorize field populated with the text you want used as context when answering questions.
Prerequisites
-
An active Serverless (vector) database.
-
An application token with the Database Administrator role.
-
A collection in your database with documents that have the
$vectorizefield populated.If you don’t already have this, follow the quickstart.
-
An OpenAI API key.
-
Python version 3.9 to 3.14.
Store your credentials
For this tutorial, store your database’s Data API endpoint, application token, and OpenAI API key in environment variables:
- Linux or macOS
-
export API_ENDPOINT=API_ENDPOINT export APPLICATION_TOKEN=APPLICATION_TOKEN export OPENAI_API_KEY=OPENAI_API_KEY - Microsoft Windows
-
set API_ENDPOINT=API_ENDPOINTset APPLICATION_TOKEN=APPLICATION_TOKENset OPENAI_API_KEY=OPENAI_API_KEY
Add the code
import os
import sys
from astrapy import DataAPIClient
from openai import OpenAI
def main() -> None:
endpoint = os.environ.get("API_ENDPOINT") (1)
application_token = os.environ.get("APPLICATION_TOKEN")
openai_api_key = os.environ.get("OPENAI_API_KEY")
keyspace = "default_keyspace" (2)
collection_name = "quickstart_collection" (3)
if not endpoint or not application_token or not openai_api_key:
raise RuntimeError(
"Environment variables API_ENDPOINT, APPLICATION_TOKEN, OPENAI_API_KEY must be defined."
)
# Instantiate the DataAPIClient and get a reference to your collection
client = DataAPIClient()
database = client.get_database(
endpoint, token=application_token, keyspace=keyspace
)
collection = database.get_collection(collection_name)
# Instantiate the OpenAI client
openai = OpenAI(api_key=openai_api_key)
# This list of messages will be sent to OpenAI with every query.
# It starts with a single system prompt and grows as the chat progresses.
messages = [
{
"role": "system",
"content": "You are an AI assistant that can answer questions based on the the context you are given. Don't mention the context, just use it to inform your answers.",
}
]
# Start the chat by writing a message to the CLI
print(
"Greetings! I am an AI assistant that is ready to help you with your questions. "
"You can ask me anything you like.\n"
'If you want to exit, type ".exit".\n'
)
user_input = input("> ")
# Run this loop continuously until the user inputs the exit command
while user_input.lower() != ".exit":
# If the user didn't input text, re-prompt them
if user_input.strip() == "":
user_input = input("> ")
continue
try:
# Perform a vector search in your collection,
# using the user input as the search string to vectorize.
# Limit the search to 10 documents.
# Use a projection to return just the $vectorize field of each document.
cursor = collection.find(
{},
sort={"$vectorize": user_input},
limit=10,
projection={"$vectorize": 1},
)
# Join the $vectorize fields of the returned documents into a single string
docs = cursor.to_list()
context = "\n".join(
(doc.get("$vectorize") or "") for doc in docs
).strip()
# Combine the user question with the context from vector search
rag_message = {
"role": "user",
"content": (
f"{context}\n---\n"
"Given the above context, answer the following question:\n"
f"{user_input}"
),
}
# Send the list of previous messages, plus the context augmented question
# to OpenAI and stream the response
stream = openai.chat.completions.create(
model="gpt-4o-mini",
messages=[*messages, rag_message],
stream=True,
)
# Write OpenAI's response to the CLI as it comes in,
# and also record it in a string
message = ""
for chunk in stream:
delta = (
(chunk.choices[0].delta.content or "")
if chunk.choices
else ""
)
if delta:
sys.stdout.write(delta)
sys.stdout.flush()
message += delta
# Record the user question, without the added context, in the list of messages
messages.append({"role": "user", "content": user_input})
# Record the OpenAI response in the list of messages
messages.append({"role": "assistant", "content": message})
# Prompt the user for their next question
user_input = input("\n\n> ")
except Exception as e:
print(str(e), file=sys.stderr)
user_input = input(
"\nSomething went wrong, try asking again\n\n> "
)
if __name__ == "__main__":
try:
main()
except Exception as err:
print(str(err), file=sys.stderr)
sys.exit(1)
| 1 | Store your database’s endpoint, application token, and OpenAI key in environment variables named API_ENDPOINT, APPLICATION_TOKEN, and OPENAI_API_KEY, as instructed in Store your credentials. |
| 2 | Change the keyspace name if your collection is in a different keyspace. |
| 3 | Change the collection name if you are not using the collection created in the quickstart. |
Test the code
-
From your terminal, run the code from the previous section.
The terminal should show the welcome message and a
>prompt. -
Enter a question. For example,
Can you recommend a book set on another planet?The terminal should print the answer from OpenAI, and give the
>prompt again. -
To exit, type
.exit.
Next steps
-
If you used the the quickstart collection, try making a collection of other data and using that instead.
-
If the user asks a question unrelated to the collection contents, the vector search still returns 10 documents. However, the similarity scores for these documents will be low, and the documents won’t be relevant to the question.
In this tutorial, similarity scores are not requested, and low-similarity results are still included in the context that is sent to OpenAI.
You can use the
includeSimilarityoption to return a similarity score for each document. Then, you can omit results with a low similarity score from the context, or prompt the user to ask a more relevant question. -
In this tutorial, the message list grows infinitely as the chat progresses. You can truncate the message list so that older messages are discarded.