Chat History Persistence API

Overview

The backend API now supports persistent chat history stored in Firestore. This allows API users to maintain conversation context across multiple API calls, similar to the frontend experience.

Features

1. Saving Chat History

When making API calls to /vac/assistant/<assistant_id>, you can save the conversation to Firestore by setting save_to_history: true in your request.

2. Reading Chat History

You can load previous conversation history from Firestore by setting read_from_history: true in your request.

API Parameters

Request Body Parameters

Parameter	Type	Default	Description
`save_to_history`	boolean	false	When true, saves the current conversation (user message and assistant response) to Firestore
`read_from_history`	boolean	false	When true, loads previous chat history from Firestore if no `chat_history` is provided
`history_limit`	integer	50	Maximum number of messages to load from history (only used when `read_from_history` is true)
`chat_history`	array	[]	Manual chat history. If provided, this takes precedence over `read_from_history`

Usage Examples

Basic Usage - Save and Read History

import requests
import json

# First request - save to history
response1 = requests.post(
    "http://localhost:1956/vac/assistant/your-assistant-id",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_TOKEN"
    },
    json={
        "user_input": "What is the weather like today?",
        "save_to_history": True
    }
)

# Second request - read from history
response2 = requests.post(
    "http://localhost:1956/vac/assistant/your-assistant-id",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_TOKEN"
    },
    json={
        "user_input": "What did I just ask you about?",
        "save_to_history": True,
        "read_from_history": True
    }
)

Custom History Limit

# Load more messages from history
response = requests.post(
    "http://localhost:1956/vac/assistant/your-assistant-id",
    json={
        "user_input": "Continue our conversation",
        "read_from_history": True,
        "history_limit": 100  # Load up to 100 messages
    }
)

Hybrid Approach - Manual + Persistent History

# You can still provide manual chat_history which takes precedence
response = requests.post(
    "http://localhost:1956/vac/assistant/your-assistant-id",
    json={
        "user_input": "Answer based on this context",
        "chat_history": [
            {"role": "human", "content": "My name is John"},
            {"role": "ai", "content": "Nice to meet you, John!"}
        ],
        "save_to_history": True  # This conversation will still be saved
    }
)

Data Storage

Firestore Structure

Messages are stored in Firestore at the following path:

assistants/{assistantId}/messages/{messageId}

Message Schema

Each message document contains:

{
    "sender": "user" | "assistant",
    "content": "The message content",
    "userName": "User's display name",
    "userEmail": "user@example.com",
    "photoURL": "URL to user's photo (optional)",
    "read": true | false,
    "timestamp": 1234567890000,  // milliseconds since epoch
    "traceId": "trace-id-if-provided",
    "thinkingContent": "Internal thinking content (for assistant messages)"
}

Best Practices

Performance: Use history_limit to control the amount of history loaded. Loading too many messages can impact performance.
Privacy: Only save conversations that need to be persistent. Sensitive data should not be saved to history.
Consistency: If using persistent history, consistently use save_to_history: true to maintain conversation continuity.
Cleanup: Implement a cleanup strategy for old messages to manage storage costs.

Integration with Frontend

This API feature provides the same chat history functionality as the frontend:

Messages saved via API appear in the frontend’s message history
Frontend conversations can be continued via API by using read_from_history
Both share the same Firestore storage structure

Error Handling

If reading from history fails, the API continues with empty history
If saving to history fails, the API response is still returned successfully
Errors are logged but don’t break the main conversation flow

Security Considerations

Authentication: Ensure proper authentication is implemented to prevent unauthorized access to chat histories
User Isolation: Each assistant’s messages are isolated in their own collection
Access Control: Implement proper Firestore security rules to restrict access

Testing

The chat history functionality is thoroughly tested with comprehensive test coverage:

test_get_chat_history_from_firestore_success: Tests successful retrieval of messages from Firestore
test_get_chat_history_from_firestore_empty: Tests behavior when no messages exist
test_get_chat_history_from_firestore_error: Tests error handling during retrieval
test_assistant_stream_read_from_history: Tests the read_from_history parameter integration
test_assistant_stream_read_history_with_manual_history: Tests that manual history takes precedence

Run tests with:

cd backend
python -m pytest tests/test_assistant_config_chat_history.py -v

Future Enhancements

Potential improvements for the chat history feature:

User-specific history isolation
Conversation sessions/threads
History search and filtering
Automatic history cleanup/archival
History export functionality