chatsnack 0.6.1

chatsnack is the easiest Python library for rapid development with OpenAI's ChatGPT API. It provides an intuitive interface for creating and managing chat-based prompts and responses, making it convenient to build complex, interactive conversations with AI.

chatsnack

chatsnack is the easiest Python library for rapid development with OpenAI's ChatGPT API. It provides an intuitive interface for creating and managing chat-based prompts and responses, making it convenient to build complex, interactive conversations with AI.

Documentation site

Setup

Got snack?

Install the chatsnack package from PyPI:

# requires Python 3.11+
pip install chatsnack

Got keys?

Add your OpenAI API key to your .env file. If you don't have a .env file, the library will create a new one for you in the local directory.

Learn More!

Read more below, watch the intro video or check out the Getting Started notebook.

Responses API Support

Chat() now defaults to the Responses family over WebSocket with session="inherit". If you stay on that default path--or explicitly choose another Responses transport-- chatsnack requires the OpenAI Python client to be openai>=2.29.0 (or newer). For explicit WebSocket support outside chatsnack's packaged dependencies, install openai[realtime]>=2.29.0.

Usage

Enjoy a Quick Snack

Easiest way to get going with chatsnack is with built-in snack packs. Each pack is a singleton ready to mingleton.

>>> from chatsnack.packs import ChatsnackHelp
>>> ChatsnackHelp.ask("What is your primary directive?")

"My primary directive is to assist users of the chatsnack Python module by answering questions and helping with any problems or concerns related to the module. I aim to provide helpful and informative responses based on the chatsnack module's documentation and best practices."

You can try out other example snack packs like Confectioner, Jolly, Chester, Jane, or Data. (Eventually there will be an easy way to create and share your own.)

Instead of .ask() we can call .chat() which will allow us to continue a conversation.

>>> mychat = ChatsnackHelp.chat("What is chatsnack?")  # submits and returns a new chat object
>>> print(mychat.response)

Chatsnack is a Python module that provides a simple and powerful interface for creating conversational agents and tools using OpenAI's ChatGPT language models. It allows you to easily build chat prompts, manage conversation flow, and integrate with ChatGPT to generate responses. With Chatsnack, you can create chatbots, AI-assisted tools, and other conversational applications using a convenient and flexible API.

Now we can add more messages to that chat however we'd like:

>>> mychat.user("Respond in only six word sentences from now on.")
>>> mychat.asst("I promise I will do so.")
>>> mychat.user("How should I spend my day?")
>>> mychat.ask()

"Explore hobbies, exercise, connect with friends."

If you want a super simple interactive conversation with you and a chatbot, you could do something like this:

from chatsnack.packs import Jolly
yourchat = Jolly  # interview a green giant
while (user_input := input("Chat with the bot: ")):
    print(f"USER: {user_input}")
    yourchat = yourchat.chat(user_input)
    print(f"THEM: {yourchat.last}")

Natural Attachments (Phase 3 style ergonomics)

For the default Responses workflows, you can pass attachments directly at query time with files= and images=:

from chatsnack import Chat

chat = Chat("Review the attachment and answer tersely.")
print(chat.ask("Summarize these.", files=["./images/chart.png", "./data/sales.csv"]))

thread = chat.chat("What stands out in this chart?", files=["./images/chart.png"])
thread = thread.chat("Now compare that with this report.", files=["./data/q2-report.pdf"])
print(thread.last)

When attachments are present, chatsnack stores the user turn as an expanded YAML block (text + files / images) while keeping plain text turns scalar-first.

Utensils (Tools)

Local Python functions and hosted OpenAI tools share one utensils=[...] surface:

from chatsnack import Chat, utensil

# Local function tools use the @utensil decorator
@utensil
def get_weather(location: str, unit: str = "celsius"):
    """Get the current weather for a location."""
    return {"temperature": 72, "condition": "sunny", "unit": unit}

# Grouped tools form searchable namespaces
crm = utensil.group("crm", "CRM tools for customer lookup.")

@crm
def get_customer(customer_id: str):
    """Look up one customer by ID."""
    return {"id": customer_id}

# Hosted tools are small named specs
docs_search = utensil.web_search(domains=["docs.python.org"], sources=True)

# Everything passes through utensils=[]
chat = Chat(
    "Use tools only when useful.",
    utensils=[get_weather, crm, utensil.tool_search, docs_search],
)
chat.reasoning.summary = "auto"

The sources=True on web_search automatically populates params.responses["include"] without manual dict mutation.

Tasty Features

There's many other tidbits covered in the notebooks, examples, and videos. Here are some of the highlights:

• Everyday Snacking
  • Chat objects
  • Chat command chaining
  • YAML convenience
  • OpenAI parameters
• Serious Snacking
  • Intense chaining
  • Fillings (e.g. nested chats and text files)
  • Snack Pack Vending Machine

Everyday Snacking

Chat objects and Chaining

from chatsnack import Chat
mychat = Chat()
mychat.system("Respond only with the word POPSICLE from now on.")
mychat.user("What is your name?")
mychat.ask()

"POPSICLE."

You can chain messages together for more complex conversations:

newchat = (
  Chat()
  .system("Respond only with the word POPSICLE from now on.")
  .user("What is your name?")
  .chat()
)
newchat.response

"POPSICLE."

Note that there are some syntax shortcuts omitted above, see the Serious Snacking section for more on those.

Yummy YAML

Generative AI gets a bit messy these days with so much text in our code. chatsnack makes it very easy to use a clean YAML syntax to load/save/edit your chat templates without so many hard-coded strings in your code.

# Every chat is totally yaml-backed, we can save/load/edit
print(newchat.yaml)
print(newchat.snapshot.path)

messages:
  - system: Respond only with the word POPSICLE from now on.
  - user: What is your name?
  - assistant: POPSICLE.

For rapid reuse, you can give your chats a name so you can save/load as needed (or using them as Fillings as we'll see later).

newchat.name = "Popsicle"
newchat.save()
print(newchat.snapshot.text)

# Load a chat from a file
midnightsnack = Chat(name="popsicle")
print(midnightsnack.ask())

"POPSICLE."

Adjusting Cooking Temperatures

By default, chatsnack uses the Responses API over WebSocket and gpt-4-turbo. If you prefer, you can change OpenAI parameters for each chat, such as the model and temperature:

from chatsnack import Chat
wisechat = Chat("Respond with professional writing based on the user query.")
wisechat.user("Author an alliterative poem about good snacks to eat with coffee.")
wisechat.model = "gpt-4"
wisechat.temperature = 0.8

This also gets captured in the YAML:

print(wisechat.yaml)

params:
  model: gpt-4
  temperature: 0.8
messages:
  - system: Respond with professional writing based on the user query.
  - user: Author an alliterative poem about good snacks to eat with coffee.

Serious Snacking

Ingredient Shortcuts

If you're wanting to minimize typing, you can use omit a couple of ingredients.

Quick System Message

For example, this:

mychat = Chat()
mychat.system("Respond hungrily")

is the same as:

# if there's only one argument or a keyword of system argument, you can omit the .system()
mychat = Chat("Respond hungrily")

Quick User Message

.ask() and .chat() are also shortcuts for .user().ask() and .user().chat() respectively. For example, this:

mychat = Chat()
mychat.system("Respond hungrily")
mychat.user("Tell me about cookies")
print(mychat.ask())

is the same as:

print(Chat("Respond hungrily").ask("Tell me about cookies"))

Basically, we assume if you're making a Chat() you'll need a system message, and if you're sending an ask() or chat() you'll need a user message. So you can omit those if you want (or use system= and user= keywords if you want to be explicit).

Quick Assistants

Also, .asst() is an alias shortcut for .assistant() if you want you code to align cleanly with other 4-letter .user() and .chat() calls.

Binge-chaining

If you're feeling wild, you can actually call any chat (like a function) and it'll submit the chat and continue, just like .chat(). This allows even more terse chaining. This can come in handy when you're looking for chain-of-thought prompting or prewriting priming.

popcorn = (
    Chat("Respond with the certainty and creativity of a professional writer.")
    ("Explain 3 rules to writing a clever poem that amazes your friends.") 
    ("Using those tips, write a scrumptious poem about popcorn.")
)
# the above is the same as Chat().system('Respond...').chat('Explain...').chat('Using...')
print(popcorn.response)

In the kitchen, I hear a popping sound, A symphony of kernels dancing around. A whiff of butter, a sprinkle of salt, My taste buds tingle, it's not their fault.

The popcorn pops, a fluffy delight, A treat for the senses, a feast for the sight. Golden and crispy, a perfect snack, A bowl of happiness, there's no going back.

I pick one up, it's warm to the touch, I savor the flavor, it's too much. A burst of butter, a crunch of salt, A symphony of flavors, it's not my fault.

I munch and crunch, it's such a delight, A scrumptious treat, a popcorn flight. A perfect snack, for any time, Popcorn, oh popcorn, you're simply divine.

Nested Chats

You can include other chats in your current chat or use {chat.___} filling expander for more dynamic AI generations:

basechat = Chat(name="ExampleIncludedChat").system("Respond only with the word CARROTSTICKS from now on.")
basechat.save()

anotherchat = Chat().include("ExampleIncludedChat")

Snacks with Fillings

You can work with Text files and YAML files to create reusable chat snippets that are filled-in before execution.

from chatsnack import Text
mytext = Text(name="SnackExplosion", content="Respond only in explosions of snack emojis and happy faces.")
mytext.save()

explosions = Chat(name="SnackSnackExplosions").system("{text.SnackExplosion}")
explosions.ask("What is your name?")

Fillings Resolving in Parallel

If you have a prompt that requires expanding multiple fillings, chatsnack will resolve them in parallel as it expands the prompt. This comes in handy with {chat.__} and {vectorsearch.__} (TODO) snack fillings.

TODO: See the notebooks for more details on this.

License

chatsnack is released under the MIT License.