Chat SDK

Overview

This guide demonstrates how to programmatically start and manage conversations with Max using the AnswerRocket Python SDK. Max is AnswerRocket's AI assistant that can analyze data, answer questions, and execute skills.

Prerequisites

AnswerRocket Python SDK installed (answerrocket-client)
Valid AnswerRocket credentials and access - Once in AnswerRocket gather an API token on your account view(bottom left on navigation bar)
A configured copilot ID(Assistant ID) - When viewing an Assistant the ID is found in the route viewable in the browser.

Basic Setup

Using Credential Arguments

For use cases of the SDK that will not operate in the MaxAI runtime, you will need to provide credentials to the AnswerRocket client.

If you have your MaxAI environment URL and your client token, you can plug them in as arguments to the AnswerRocket client initializer.

from answer_rocket import AnswerRocketClient

# Initialize the client
client = AnswerRocketClient(url='https://my.api.url', token='my_token_from_max')

# Your copilot ID (get this from the AnswerRocket UI)
copilot_id = "your-copilot-id-here"

Using Environment Variables (or MaxAI runtime)

Alternatively, if your code will be executed in a skill on the MaxAI runtime or you already have the AR_URL and AR_TOKEN environment variables set, you can simply initialize the client without arguments.

from answer_rocket import AnswerRocketClient

# Initialize the client
client = AnswerRocketClient()

# Your copilot ID (get this from the AnswerRocket UI)
copilot_id = "your-copilot-id-here"

Starting a New Conversation

Method 1: Direct Question (Synchronous)

The simplest way to ask a question and wait for a complete response:

# Ask a question and get the complete response
response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="What was the sales performance for Q4 2023?"
)

print(f"Answer: {response.answer.message}")
print(f"Entry ID: {response.id}")

Method 2: Create Thread First (Recommended for Multi-turn Conversations)

For conversations with multiple back-and-forth exchanges:

# Create a new conversation thread
thread = client.chat.create_new_thread(copilot_id=copilot_id)
thread_id = thread.id

# Ask the first question
response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="Analyze the market share for our top brands",
    thread_id=thread_id
)

# Ask follow-up questions in the same thread
followup_response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="What were the key drivers of change?",
    thread_id=thread_id
)

Method 3: Asynchronous (Queue and Poll)

For long-running questions where you don't want to block:

# Queue the question for processing
queued_entry = client.chat.queue_chat_question(
    question="Perform comprehensive brand analysis for 2023",
    thread_id=thread_id
)

entry_id = queued_entry.id
print(f"Question queued with ID: {entry_id}")

# Poll for completion (you'd implement proper polling logic)
import time
while True:
    entry = client.chat.get_chat_entry(entry_id)
    if entry.answer.has_finished:
        print(f"Answer: {entry.answer.message}")
        if entry.answer.error:
          print(f"Answer finished with error: {entry.answer.error}")
        break

    else:
        print("Waiting on answer…")
        time.sleep(5)  # Wait 5 seconds before checking again

Advanced Options

Forcing Specific Skills

You can limit Max to specific skills or guarantee execution of a particular skill:

# Limit to specific skills
response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="Analyze brand performance",
    indicated_skills=["brand_drivers", "sql_executor"]
)

# Guarantee execution of a specific skill (list with one skill)
response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="Run brand analysis for Barilla",
    indicated_skills=["brand_drivers"]  # Will definitely use this skill
)

Model Overrides

Override the default AI models used:

response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="Analyze the data trends",
    model_overrides={
        "CHAT": "gpt-4",
        "NARRATIVE": "claude-3-opus"
    }
)

Conversation History

Provide explicit conversation history:

history = [
    {"role": "user", "content": "What is our market share?"},
    {"role": "assistant", "content": "Your market share is 23.5%"},
    {"role": "user", "content": "How does that compare to last year?"}
]

response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="What were the drivers of the change?",
    history=history
)

Managing Conversations

Retrieve Thread History

# Get all entries in a thread
entries = client.chat.get_entries(thread_id=thread_id)

for entry in entries:
    print(f"Q: {entry.question.nl}")
    if entry.answer:
        print(f"A: {entry.answer.message")
    print("---")

Working with Results

Accessing Answer Data

response = client.chat.ask_question(
    copilot_id=copilot_id,
    question="Show me sales data"
)

# Access the narrative response
narrative = response.answer.narrative


)

Feedback and Evaluation

Provide Feedback

# Give positive feedback
client.chat.add_feedback(
    entry_id=response.id,
    feedback_type="CHAT_POSITIVE",
    feedback_text="Great analysis, very helpful!"
)

# Give negative feedback
client.chat.add_feedback(
    entry_id=response.id,
    feedback_type="CHAT_NEGATIVE",
    feedback_text="The analysis missed key insights"

Run Evaluations

# Run custom evaluations on responses
evaluation = client.chat.evaluate_entry(
    entry_id=response.id,
    evals=["accuracy", "completeness", "clarity"]
)

Complete Example

from answer_rocket import AnswerRocketClient
import time

def main():
    # Initialize client
    client = AnswerRocketClient()
    copilot_id = "your-copilot-id"
    
    try:
        # Create conversation thread
        thread = client.chat.create_new_thread(copilot_id=copilot_id)
        print(f"Created thread: {thread.id}")
        
        # Ask initial question
        response = client.chat.ask_question(
            copilot_id=copilot_id,
            question="What is the market share for Barilla in 2022 vs 2021?",
            thread_id=thread.id,
            indicated_skills=["brand_drivers"]
        )
        
        print(f"Answer: {response.answer.narrative}")
        
        # Ask follow-up
        followup = client.chat.ask_question(
            copilot_id=copilot_id,
            question="What were the key drivers of this change?",
            thread_id=thread.id
        )
        
        print(f"Follow-up: {followup.answer.narrative}")
        
        # Provide feedback
        client.chat.add_feedback(
            entry_id=response.id,
            feedback_type="CHAT_POSITIVE",
            feedback_text="Excellent brand analysis!"
        )
        
    except Exception as e:
        print(f"Error: {str(e)}")

if __name__ == "__main__":
    main()