Skip to main content

AI Chat Sessions

The chats.py module, part of the google.genai library, is designed to facilitate and manage multi-turn conversations (chat sessions) with a Generative AI model, such as Google's Gemini. It abstracts away the complexities of managing conversation history, sending messages, and processing responses, providing a higher-level interface for building conversational AI applications.

Core Purpose​

The primary purpose of this module is to enable developers to create and manage persistent chat sessions with a large language model (LLM). This includes:

  1. Maintaining Conversation History: Automatically keeps track of user inputs and model responses, ensuring that each subsequent turn in the conversation has the necessary context.
  2. Sending Messages: Provides methods to send messages to the AI model within a chat session.
  3. Handling Responses: Manages the retrieval and processing of model responses, including streaming responses.
  4. History Validation: Incorporates logic to validate the integrity and structure of content within the conversation history, distinguishing between "comprehensive" (all interactions) and "curated" (valid turns for context) history.
  5. Asynchronous Operations: Offers both synchronous (Chat) and asynchronous (AsyncChat) interfaces for flexible integration into different application architectures.

Key Classes and Their Functionality​

  • _BaseChat: An abstract base class that encapsulates the common logic for managing chat history, including:

    • _comprehensive_history: Stores all turns of the chat, including potentially invalid or rejected model outputs.
    • _curated_history: Stores only the valid turns that are used as context for subsequent model requests. This is crucial for maintaining coherent conversations.
    • record_history(): Adds new user inputs and model outputs to both histories, validating the model's output.
    • get_history(): Allows retrieval of either the comprehensive or curated history.

  • Chat:

    • Synchronous Chat Session: Represents a single, synchronous chat session with a Generative AI model.
    • send_message(message, config=None): Sends a user message and returns the model's complete response in a blocking call. The chat history (curated) is automatically included as context.
    • send_message_stream(message, config=None): Sends a user message and yields the model's response in chunks (streaming). This is useful for displaying partial responses as they are generated.

  • AsyncChat:

    • Asynchronous Chat Session: Similar to Chat, but provides asynchronous methods (async def) for non-blocking operations, suitable for web servers, UIs, or other async frameworks.
    • await send_message(message, config=None): Asynchronous version of send_message.
    • async for chunk in await send_message_stream(message, config=None): Asynchronous version of send_message_stream.

  • Chats:

    • Synchronous Chat Factory: A utility class to create new Chat instances. It takes an underlying Models object (which handles the actual API calls to the generative model).
    • create(model, config=None, history=None): Instantiates and returns a new Chat object, initialized with a specified model and optional initial history.

  • AsyncChats:

    • Asynchronous Chat Factory: Similar to Chats, but creates AsyncChat instances, taking an AsyncModels object.
    • create(model, config=None, history=None): Instantiates and returns a new AsyncChat object.

Use Cases​

This module is fundamental for any application that requires interactive, multi-turn conversations with a Generative AI model.

  1. Building Conversational AI Agents/Chatbots:

    • Customer Support Bots: Automatically answer common questions, escalate to human agents when needed, and maintain context across a user's queries.
    • Virtual Assistants: Provide information, perform tasks, and engage in free-form conversation.
    • Interactive Storytelling/Gaming: Create dynamic narratives where the AI's responses evolve based on player input.

  2. Content Generation with Context:

    • Creative Writing Assistants: Assist writers by generating text, brainstorming ideas, or refining content, remembering previous turns and prompts.
    • Code Generation Tools: Help developers by generating code snippets or explaining concepts in a conversational manner, keeping track of the project's context.

  3. Educational Tools:

    • Personalized Tutors: Provide explanations and answer questions in an ongoing dialogue, adapting to the student's learning pace and previous interactions.
    • Language Learning Apps: Engage users in conversational practice, correcting grammar or suggesting vocabulary.

  4. Data Exploration and Analysis (Conversational Interface):

    • Allow users to query data or generate reports through natural language conversation, where follow-up questions leverage the context of previous queries.

  5. Interactive Development Environments:

    • Integrate directly into IDEs or command-line tools to provide AI assistance that understands the ongoing coding context.

Example Usage (from comments)​

Synchronous Chat:

import google.generativeai as genai

# Assuming 'client' is an initialized genai client
client = genai.GenerativeModel('gemini-pro') # Placeholder for actual client initialization
chat = client.chats.create(model='gemini-pro') # Using client.chats.create
response = chat.send_message('tell me a story')
print(response.text)

# Streaming response
for chunk in chat.send_message_stream('continue the story'):
  print(chunk.text, end='')

Asynchronous Chat:

import google.generativeai as genai

# Assuming 'client.aio' is an initialized asynchronous client
async_client = genai.AsyncGenerativeModel('gemini-pro') # Placeholder for actual client initialization
chat = async_client.aio.chats.create(model='gemini-pro') # Using client.aio.chats.create
response = await chat.send_message('tell me a story')
print(response.text)

# Streaming response asynchronously
async for chunk in await chat.send_message_stream('continue the story'):
  print(chunk.text, end='')

In essence, chats.py provides the foundational building blocks for creating stateful, interactive, and intelligent conversational experiences powered by Google's Generative AI models.