ApalaClient

Main client for interacting with the Phoenix Message Analysis API.

class apala_client.client.ApalaClient(api_key, base_url='http://localhost:4000')[source]

Bases: object

Client for Phoenix Message Analysis Services.

Provides authentication and methods for message processing and feedback.

Parameters:

api_key (str)
base_url (str)

__init__(api_key, base_url='http://localhost:4000')[source]

Initialize the client.

Parameters:

api_key (str) – Your API key for authentication
base_url (str) – Base URL of the Phoenix server

authenticate()[source]

Exchange API key for JWT tokens.

Return type:

AuthResponse

Returns:

Authentication response data

Raises:

requests.HTTPError – If authentication fails
requests.RequestException – For network-related errors

refresh_access_token()[source]

Refresh the access token using the refresh token.

Return type:

RefreshResponse

Returns:

Refresh response data

Raises:

requests.HTTPError – If token refresh fails
requests.RequestException – For network-related errors

message_process(message_history, candidate_message, customer_id, zip_code, company_guid)[source]

Process customer message history and candidate message.

Parameters:

message_history (List[Message]) – List of customer messages
candidate_message (Message) – The candidate response message
customer_id (str) – Customer UUID
zip_code (str) – Customer’s 5-digit zip code
company_guid (str) – Company UUID

Return type:

MessageProcessingResponse

Returns:

Processing response data

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

optimize_message(message_history, candidate_message, customer_id, zip_code, company_guid, metadata=None)[source]

Optimize a message for maximum customer engagement.

Parameters:

message_history (List[Message]) – List of customer messages
candidate_message (Message) – The candidate message to optimize
customer_id (str) – Customer UUID
zip_code (str) – Customer’s 5-digit zip code
company_guid (str) – Company UUID
metadata (Optional[CustomerMetadata]) – Optional customer metadata for enhanced personalization

Return type:

MessageOptimizationResponse

Returns:

Optimization response with optimized_message and recommended_channel

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

Example

>>> from apala_client import CustomerMetadata, CreditScoreBin, ApplicationReason
>>> metadata = CustomerMetadata(
...     is_repeat_borrower=1,
...     credit_score_bin=CreditScoreBin.SCORE_650_700,
...     application_reason=ApplicationReason.HOME_IMPROVEMENT
... )
>>> result = client.optimize_message(
...     message_history=messages,
...     candidate_message=candidate,
...     customer_id=customer_id,
...     zip_code="90210",
...     company_guid=company_guid,
...     metadata=metadata
... )

message_feedback(feedback_list)[source]

Submit feedback for multiple processed messages using bulk endpoint.

Parameters:

feedback_list (List[Dict[str, any]]) – List of feedback dictionaries, each containing: - message_id: str - The message UUID - customer_responded: bool - Whether customer responded - score: int - Quality score (0-100)

Return type:

BulkFeedbackResponse

Returns:

Bulk feedback submission response

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

submit_single_feedback(message_id, customer_responded, score, actual_sent_message=None)[source]

Submit feedback for a single processed message.

Parameters:

message_id (str) – The message UUID from optimization response
customer_responded (bool) – Whether the customer responded
score (int) – Quality score (0-100)
actual_sent_message (Optional[str]) – Optional - The actual message content sent to the customer. Useful if you modified the optimized message before sending.

Return type:

FeedbackResponse

Returns:

Feedback submission response

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

submit_feedback_bulk(feedback_list)[source]

Submit feedback for multiple messages in bulk.

Parameters:

feedback_list (List[Dict[str, any]]) – List of feedback dictionaries, each containing: - message_id: str - The message UUID - customer_responded: bool - Whether customer responded - score: int - Quality score (0-100) - actual_sent_message: str (optional) - The actual message content sent to customer

Return type:

BulkFeedbackResponse

Returns:

Bulk feedback submission response with success status, count, and individual feedback items

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

Example

>>> feedback_list = [
...     {
...         "message_id": "550e8400-e29b-41d4-a716-446655440000",
...         "customer_responded": True,
...         "score": 85,
...         "actual_sent_message": "Hi! Ready to help with your loan."
...     },
...     {
...         "message_id": "660e8400-e29b-41d4-a716-446655440001",
...         "customer_responded": False,
...         "score": 60
...     }
... ]
>>> response = client.submit_feedback_bulk(feedback_list)
>>> print(f"Submitted {response['count']} feedback items")

close()[source]

Close the HTTP session.

Return type:: None

The ApalaClient is the main interface for interacting with the Phoenix Message Analysis API.

Overview

The client provides the following functionality:

Authentication: Automatic JWT token management with refresh
Message Processing: Process customer message histories and candidate responses
Message Optimization: Enhance messages for better customer engagement
Feedback Tracking: Submit performance feedback for processed messages

Example Usage

Basic Client Setup

from apala_client import ApalaClient

# Initialize the client
client = ApalaClient(
    api_key="your-api-key",
    base_url="https://your-server.com"
)

# Authenticate (gets JWT tokens)
auth_response = client.authenticate()
print(f"Authenticated as: {auth_response['company_name']}")

Message Processing

from apala_client import Message

# Create message history
messages = [
    Message(content="I need help with my loan", channel="EMAIL"),
    Message(content="What are your rates?", channel="SMS")
]

# Define candidate response
candidate = Message(
    content="Our rates start at 3.5% APR. Let me help you!",
    channel="EMAIL"
)

# Process through AI system
response = client.message_process(
    message_history=messages,
    candidate_message=candidate,
    customer_id="customer-uuid-here",
    zip_code="12345",
    company_guid="company-uuid-here"
)

# Access typed response
message_id = response["candidate_message"]["message_id"]
print(f"Processed message ID: {message_id}")

Message Optimization

# Optimize message for better engagement
optimization = client.optimize_message(
    message_history=messages,
    candidate_message=candidate,
    customer_id="customer-uuid",
    zip_code="12345",
    company_guid="company-uuid"
)

print(f"Original: {optimization['original_message']}")
print(f"Optimized: {optimization['optimized_message']}")
print(f"Recommended channel: {optimization['recommended_channel']}")

Feedback Submission

from apala_client import MessageFeedback

# Create feedback after customer interaction
feedback = MessageFeedback(
    original_message_id="message-id-from-processing",
    sent_message_content="The actual message sent",
    customer_responded=True,
    quality_score=88,
    time_to_respond_ms=1200000  # 20 minutes
)

# Submit feedback
result = client.submit_single_feedback(feedback)
print(f"Feedback ID: {result['feedback_id']}")

Error Handling

The client uses standard requests library exceptions:

import requests

try:
    response = client.message_process(...)
except requests.HTTPError as e:
    print(f"HTTP error: {e.response.status_code}")
except requests.ConnectionError as e:
    print(f"Connection error: {e}")
except requests.RequestException as e:
    print(f"Request error: {e}")
except ValueError as e:
    print(f"Validation error: {e}")

Class Reference

class apala_client.client.ApalaClient(api_key, base_url='http://localhost:4000')[source]

Client for Phoenix Message Analysis Services.

Provides authentication and methods for message processing and feedback.

Parameters:

api_key (str)
base_url (str)

__init__(api_key, base_url='http://localhost:4000')[source]

Initialize the client.

Parameters:

api_key (str) – Your API key for authentication
base_url (str) – Base URL of the Phoenix server

authenticate()[source]

Exchange API key for JWT tokens.

Return type:

AuthResponse

Returns:

Authentication response data

Raises:

requests.HTTPError – If authentication fails
requests.RequestException – For network-related errors

refresh_access_token()[source]

Refresh the access token using the refresh token.

Return type:

RefreshResponse

Returns:

Refresh response data

Raises:

requests.HTTPError – If token refresh fails
requests.RequestException – For network-related errors

message_process(message_history, candidate_message, customer_id, zip_code, company_guid)[source]

Process customer message history and candidate message.

Parameters:

message_history (List[Message]) – List of customer messages
candidate_message (Message) – The candidate response message
customer_id (str) – Customer UUID
zip_code (str) – Customer’s 5-digit zip code
company_guid (str) – Company UUID

Return type:

MessageProcessingResponse

Returns:

Processing response data

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

optimize_message(message_history, candidate_message, customer_id, zip_code, company_guid, metadata=None)[source]

Optimize a message for maximum customer engagement.

Parameters:

message_history (List[Message]) – List of customer messages
candidate_message (Message) – The candidate message to optimize
customer_id (str) – Customer UUID
zip_code (str) – Customer’s 5-digit zip code
company_guid (str) – Company UUID
metadata (Optional[CustomerMetadata]) – Optional customer metadata for enhanced personalization

Return type:

MessageOptimizationResponse

Returns:

Optimization response with optimized_message and recommended_channel

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

Example

>>> from apala_client import CustomerMetadata, CreditScoreBin, ApplicationReason
>>> metadata = CustomerMetadata(
...     is_repeat_borrower=1,
...     credit_score_bin=CreditScoreBin.SCORE_650_700,
...     application_reason=ApplicationReason.HOME_IMPROVEMENT
... )
>>> result = client.optimize_message(
...     message_history=messages,
...     candidate_message=candidate,
...     customer_id=customer_id,
...     zip_code="90210",
...     company_guid=company_guid,
...     metadata=metadata
... )

message_feedback(feedback_list)[source]

Submit feedback for multiple processed messages using bulk endpoint.

Parameters:

feedback_list (List[Dict[str, any]]) – List of feedback dictionaries, each containing: - message_id: str - The message UUID - customer_responded: bool - Whether customer responded - score: int - Quality score (0-100)

Return type:

BulkFeedbackResponse

Returns:

Bulk feedback submission response

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

submit_single_feedback(message_id, customer_responded, score, actual_sent_message=None)[source]

Submit feedback for a single processed message.

Parameters:

message_id (str) – The message UUID from optimization response
customer_responded (bool) – Whether the customer responded
score (int) – Quality score (0-100)
actual_sent_message (Optional[str]) – Optional - The actual message content sent to the customer. Useful if you modified the optimized message before sending.

Return type:

FeedbackResponse

Returns:

Feedback submission response

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

submit_feedback_bulk(feedback_list)[source]

Submit feedback for multiple messages in bulk.

Parameters:

feedback_list (List[Dict[str, any]]) – List of feedback dictionaries, each containing: - message_id: str - The message UUID - customer_responded: bool - Whether customer responded - score: int - Quality score (0-100) - actual_sent_message: str (optional) - The actual message content sent to customer

Return type:

BulkFeedbackResponse

Returns:

Bulk feedback submission response with success status, count, and individual feedback items

Raises:

requests.HTTPError – If the request fails
requests.RequestException – For network-related errors

Example

>>> feedback_list = [
...     {
...         "message_id": "550e8400-e29b-41d4-a716-446655440000",
...         "customer_responded": True,
...         "score": 85,
...         "actual_sent_message": "Hi! Ready to help with your loan."
...     },
...     {
...         "message_id": "660e8400-e29b-41d4-a716-446655440001",
...         "customer_responded": False,
...         "score": 60
...     }
... ]
>>> response = client.submit_feedback_bulk(feedback_list)
>>> print(f"Submitted {response['count']} feedback items")

close()[source]

Close the HTTP session.

Return type:: None