Data Models

Data models for Apala API client.

All models use Pydantic for type safety and validation.

class apala_client.models.AuthResponse(**data)[source]

Bases: BaseModel

Authentication response from the server.

Parameters:: data (Any)

access_token: str

refresh_token: str

token_type: str

expires_in: int

company_id: str

company_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.RefreshResponse(**data)[source]

Bases: BaseModel

Token refresh response from the server.

Parameters:: data (Any)

access_token: str

expires_in: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.CandidateMessageResponse(**data)[source]

Bases: BaseModel

Candidate message in processing response.

Parameters:: data (Any)

content: str

channel: str

message_id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageProcessingResponse(**data)[source]

Bases: BaseModel

Message processing response from the server.

Parameters:: data (Any)

company: str

customer_id: str

candidate_message: CandidateMessageResponse

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageOptimizationResponse(**data)[source]

Bases: BaseModel

Message optimization response from the server.

Parameters:: data (Any)

message_id: str

optimized_message: str

recommended_channel: str

original_message: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.FeedbackResponse(**data)[source]

Bases: BaseModel

Feedback submission response from the server.

Parameters:: data (Any)

id: str

message_id: str

customer_responded: bool

score: int

actual_sent_message: Optional[str]

inserted_at: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.FeedbackItemResponse(**data)[source]

Bases: BaseModel

Individual feedback item in bulk response.

Parameters:: data (Any)

id: str

message_id: str

customer_responded: bool

score: int

actual_sent_message: Optional[str]

inserted_at: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.BulkFeedbackResponse(**data)[source]

Bases: BaseModel

Bulk feedback submission response from the server.

Parameters:: data (Any)

success: bool

count: int

feedback: List[FeedbackItemResponse]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.Message(**data)[source]

Bases: BaseModel

Represents a customer message.

Parameters:: data (Any)

content: str

channel: str

message_id: Optional[str]

send_timestamp: Optional[str]

reply_or_not: bool

classmethod validate_channel(v)[source]

Validate channel is one of the allowed values.

Parameters:: v (str)
Return type:: str

model_post_init(_Message__context)[source]

Generate message_id and timestamp if not provided.

Parameters:: _Message__context (Any)
Return type:: None

to_dict()[source]

Convert to dictionary for API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageFeedback(**data)[source]

Bases: BaseModel

Represents feedback for a processed message.

Parameters:: data (Any)

original_message_id: str

sent_message_content: str

customer_responded: bool

quality_score: int

time_to_respond_ms: Optional[int]

to_dict()[source]

Convert to dictionary for API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class apala_client.models.MessageHistory(**data)[source]

Bases: BaseModel

Represents a collection of customer messages and a candidate response.

Parameters:: data (Any)

messages: List[Message]

candidate_message: Message

customer_id: str

zip_code: str

company_guid: str

classmethod validate_uuid(v)[source]

Validate UUID format.

Parameters:: v (str)
Return type:: str

to_processing_dict()[source]

Convert to dictionary for message processing API requests.

Return type:: Dict[str, Any]

to_optimization_dict()[source]

Convert to dictionary for message optimization API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The data models provide type-safe interfaces for working with messages and feedback.

Message Model

class apala_client.models.Message(**data)[source]

Represents a customer message.

Parameters:: data (Any)

content: str

channel: str

message_id: Optional[str]

send_timestamp: Optional[str]

reply_or_not: bool

classmethod validate_channel(v)[source]

Validate channel is one of the allowed values.

Parameters:: v (str)
Return type:: str

model_post_init(_Message__context)[source]

Generate message_id and timestamp if not provided.

Parameters:: _Message__context (Any)
Return type:: None

to_dict()[source]

Convert to dictionary for API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The Message class represents both customer messages and candidate responses.

Fields:

content (str): The message text content
channel (str): Communication channel - “SMS”, “EMAIL”, or “OTHER”
message_id (Optional[str]): Unique message identifier (auto-generated if None)
send_timestamp (Optional[str]): ISO timestamp (auto-generated if None)
reply_or_not (bool): Whether this message is a reply (default: False)

Example:

from apala_client import Message

# Customer message
customer_msg = Message(
    content="I'm interested in a home loan",
    channel="EMAIL",
    reply_or_not=False
)

# Candidate response
response_msg = Message(
    content="Great! Let me help you with loan options.",
    channel="EMAIL"
)

# Convert to dict for API calls
data = customer_msg.to_dict()

MessageFeedback Model

class apala_client.models.MessageFeedback(**data)[source]

Represents feedback for a processed message.

Parameters:: data (Any)

original_message_id: str

sent_message_content: str

customer_responded: bool

quality_score: int

time_to_respond_ms: Optional[int]

to_dict()[source]

Convert to dictionary for API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The MessageFeedback class tracks performance metrics for processed messages.

Fields:

original_message_id (str): ID from message processing response
sent_message_content (str): Actual message content sent to customer
customer_responded (bool): Whether the customer responded
quality_score (int): Quality rating from 0-100
time_to_respond_ms (Optional[int]): Customer response time in milliseconds

Example:

from apala_client import MessageFeedback

feedback = MessageFeedback(
    original_message_id="msg_12345",
    sent_message_content="Thank you for your inquiry!",
    customer_responded=True,
    quality_score=85,
    time_to_respond_ms=1800000  # 30 minutes
)

# Convert to dict for API submission
data = feedback.to_dict()

MessageHistory Model

class apala_client.models.MessageHistory(**data)[source]

Represents a collection of customer messages and a candidate response.

Parameters:: data (Any)

messages: List[Message]

candidate_message: Message

customer_id: str

zip_code: str

company_guid: str

classmethod validate_uuid(v)[source]

Validate UUID format.

Parameters:: v (str)
Return type:: str

to_processing_dict()[source]

Convert to dictionary for message processing API requests.

Return type:: Dict[str, Any]

to_optimization_dict()[source]

Convert to dictionary for message optimization API requests.

Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

The MessageHistory class bundles together all data needed for message processing.

Fields:

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

Validation:

The __post_init__ method automatically validates:

UUIDs are properly formatted
Zip code is exactly 5 digits
All message channels are valid (“SMS”, “EMAIL”, “OTHER”)

Example:

from apala_client import Message, MessageHistory

history = MessageHistory(
    messages=[
        Message(content="Hello", channel="EMAIL"),
        Message(content="Need help", channel="SMS")
    ],
    candidate_message=Message(
        content="How can I assist you?",
        channel="EMAIL"
    ),
    customer_id="550e8400-e29b-41d4-a716-446655440000",
    zip_code="90210",
    company_guid="550e8400-e29b-41d4-a716-446655440001"
)

# Convert for processing API
processing_data = history.to_processing_dict()

# Convert for optimization API
optimization_data = history.to_optimization_dict()

Model Validation

All models include automatic validation:

UUID Validation: Customer IDs and company GUIDs must be valid UUID format
Zip Code Validation: Must be exactly 5 digits
Channel Validation: Must be one of: “SMS”, “EMAIL”, “OTHER”
Content Validation: Message content cannot be empty

Example of Validation Errors:

# This will raise ValueError
try:
    invalid_history = MessageHistory(
        messages=[],
        candidate_message=candidate,
        customer_id="not-a-uuid",  # Invalid UUID
        zip_code="123",            # Too short
        company_guid="also-invalid"
    )
except ValueError as e:
    print(f"Validation error: {e}")

Best Practices

Message Creation

Always specify the channel explicitly
Let message_id and send_timestamp auto-generate for new messages
Use descriptive content that clearly represents the customer’s intent

Feedback Tracking

Submit feedback for every message you send to customers
Use realistic quality scores (0-100)
Include response time when available for better analytics

Data Validation

Use proper UUID format for customer and company IDs
Ensure zip codes are exactly 5 digits
Validate message content before processing