jumpad-sdk-client 0.1.1

A powerful and user-friendly Python client for interacting with the Jumpad AI Agent SDK

Jumpad SDK Client

A powerful and user-friendly Python client for interacting with the Jumpad AI Agent SDK.

Features

• Easy-to-use SDK with simplified API that abstracts away complexity
• Automatic handling of chat sessions and message sequences
• Two supported approaches: simplified for ease of use, traditional for detailed control
• Automatic tracking of conversation history
• Duplicate message prevention
• Helper methods for extracting different types of messages
• Pretty-formatted conversation output

Installation

Make sure you have the latest version of pip before installing:

pip install --upgrade pip

Install from PyPI:

pip install jumpad-sdk-client

Quick Start

from jumpad_sdk_client import LLMAgentClient

# Initialize the client with your API key and Agent ID
BASE_URL = "your_fusion_workspace_instance_URL"
API_KEY = "your_api_key_here"
AGENT_ID = "your_agent_id_here"

client = LLMAgentClient(endpoint=BASE_URL, api_key=API_KEY, agent_id=AGENT_ID)

# Simply send a message and get a response - the SDK handles everything
agent_response = client.get_agent_response("Hi Agent, can you introduce yourself?")
print(f"Agent says: {agent_response}")

# Send a follow-up message - no need to manage chat IDs
follow_up_response = client.get_agent_response("Thanks! Now tell me a fun fact.")
print(f"Agent's reply: {follow_up_response}")

# If you need the chat ID for any reason, you can get it anytime
chat_id = client.get_chat_id()
print(f"Chat ID: {chat_id}")

# If you need the raw response data
raw_response = client.get_raw_agent_response()
print(f"Raw response: {raw_response}")

Working with Conversations

Viewing the Complete Conversation

# Get nicely formatted conversation history
formatted_history = client.get_tracked_messages(chat_id, format_output=True)
print(formatted_history)

# Output example:
# ===== Conversation History =====
#
# 1. 👤 You: Hi Agent, can you introduce yourself?
#
# 2. 🤖 Agent: Hello! I'm the Jumpad AI assistant...
#
# 3. 👤 You: Thanks! Now tell me a fun fact.
#
# 4. 🤖 Agent: Here's a fun fact: Honey never spoils...

Working with User Messages

# Get all user messages in formatted output
try:
    user_messages = client.get_tracked_user_messages(chat_id, format_output=True)
    print(user_messages)
except ValueError as e:
    print(f"Error: {e}")

# Get raw user message data for processing
try:
    user_messages_data = client.get_tracked_user_messages(chat_id)
    for msg in user_messages_data:
        print(f"ID: {msg.get('id')}, Message: {msg.get('message')}")
except ValueError as e:
    print(f"Error: {e}")

Working with Agent Messages

# Get all agent responses in formatted output
try:
    agent_messages = client.get_tracked_agent_messages(chat_id, format_output=True)
    print(agent_messages)
except ValueError as e:
    print(f"Error: {e}")

# Get raw agent message data for processing
try:
    agent_messages_data = client.get_tracked_agent_messages(chat_id)
    for msg in agent_messages_data:
        print(f"ID: {msg.get('id')}, Message: {msg.get('message')}")
except ValueError as e:
    print(f"Error: {e}")

Advanced Usage

Traditional API Usage (Still Supported)

If you prefer the previous style of explicit chat management:

# Start a chat session explicitly
response = client.start_chat(initial_message="Hello agent!")

# Extract the chat ID
chat_id = client.get_chat_id_from_response(response)

# Get the agent's response
agent_response = client.get_agent_response_from_chat(response)

# Send a follow-up message to the specific chat
send_response = client.send_message(chat_id=chat_id, message="Follow up question")

# Get the agent's reply
agent_reply = client.get_agent_reply_to_message(send_response)

Getting Chat Details

# Get chat metadata without messages
chat_details = client.get_chat_history(chat_id)
print(f"Chat title: {chat_details.get('title')}")
print(f"Chat created at: {chat_details.get('created_at')}")

# Get chat with messages
chat_with_messages = client.get_chat_with_messages(chat_id)

Extracting Message Details

# After sending a message either with the simplified or traditional API
# you can extract specific details if needed

# Extract the sent message content
message_content = client.get_sent_message_content(client.get_raw_agent_response())

# Extract the sent message ID
message_id = client.get_sent_message_id(client.get_raw_agent_response())

Getting Raw SDK Responses

# Get the raw SDK response
raw_response = client.get_raw_response(response)
print(json.dumps(raw_response, indent=2))

Error Handling

The client includes comprehensive error handling:

from jumpad_sdk_client import LLMAgentClient, LLMAgentError

try:
    # Your code here
    response = client.send_message(chat_id, "Hello")
except LLMAgentError as e:
    print(f"SDK Error: {e.status_code} - {e.error_message}")
    if e.response_body:
        print(f"Response Body: {e.response_body}")
except ValueError as e:
    print(f"Value Error: {e}")
except Exception as e:
    print(f"Unexpected Error: {e}")

Getting Help

You can use Python's built-in help system to learn more about the package:

import jumpad_sdk_client
help(jumpad_sdk_client)  # Show module documentation

from jumpad_sdk_client import LLMAgentClient
help(LLMAgentClient)  # Show class documentation 
help(LLMAgentClient.send_message)  # Show method documentation

Complete Example

import os
import json
from jumpad_sdk_client import LLMAgentClient, LLMAgentError

# Configuration
BASE_URL = "https://fusion-workspace.jumpad.ai"
API_KEY = "your_api_key_here"  # Replace with your actual API key
AGENT_ID = "your_agent_id_here"  # Replace with your actual agent ID

def main():
    try:
        # Initialize the client with your agent ID
        client = LLMAgentClient(endpoint=BASE_URL, api_key=API_KEY, agent_id=AGENT_ID)
        print("Client initialized.")

        # Send the first message and get the agent's response
        agent_response = client.get_agent_response("Hi Agent, can you introduce yourself?")
        print(f"Agent says: {agent_response}")
        
        # Send a follow-up message
        follow_up_response = client.get_agent_response("Thanks! Tell me about your capabilities.")
        print(f"Agent reply: {follow_up_response}")
        
        # Get the chat ID if needed for reference
        chat_id = client.get_chat_id()
        print(f"Conversation is happening in chat: {chat_id}")
        
        # Display the complete conversation
        print("\nComplete conversation:")
        conversation = client.get_tracked_messages(chat_id, format_output=True)
        print(conversation)
        
    except LLMAgentError as e:
        print(f"SDK Error: {e.status_code} - {e.error_message}")
        if e.response_body:
            print(f"Response: {json.dumps(e.response_body, indent=2)}")
    except ValueError as e:
        print(f"Value Error: {e}")
    except Exception as e:
        print(f"Unexpected Error: {e}")

if __name__ == "__main__":
    main()

SDK Reference

LLMAgentClient

• __init__(endpoint: str, api_key: str, agent_id: Optional[str] = None) - Initialize the client with optional agent_id
• start_chat(agent_id: Optional[str] = None, initial_message: str) - Start a new chat
• send_message(chat_id: Optional[str] = None, message: str) - Send a message to a chat

Simplified API Methods

• get_agent_response(message: Optional[str] = None) - Get agent's response (handles chat initiation automatically)
• get_chat_id() - Get current chat ID without needing parameters
• get_raw_agent_response() - Get raw response data from last interaction

Traditional Helper Methods

• get_chat_id_from_response(response) - Extract chat ID from response
• get_agent_response_from_chat(response) - Extract agent response
• get_sent_message_content(response) - Get content of sent message
• get_sent_message_id(response) - Get ID of sent message
• get_agent_reply_to_message(response) - Get agent's reply to a message

Message Tracking

• get_tracked_messages(chat_id, format_output=False) - Get all messages
• get_tracked_user_messages(chat_id, format_output=False) - Get user messages
• get_tracked_agent_messages(chat_id, format_output=False) - Get agent messages

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.