letschatty 0.4.280__py3-none-any.whl → 0.4.343__py3-none-any.whl

letschatty/models/company/assets/ai_agents_v2/chatty_ai_agent_in_chat.py

@@ -7,15 +7,16 @@ independently without loading entire chat documents.
 """
 
 from letschatty.models.analytics.events.base import EventType
+from enum import StrEnum
 from pydantic import BaseModel, Field, field_validator, ConfigDict
 from datetime import datetime
 from zoneinfo import ZoneInfo
 from typing import Optional, ClassVar, List, Dict, Any
-from enum import StrEnum
 from letschatty.models.base_models.chatty_asset_model import CompanyAssetModel, ChattyAssetPreview
 from letschatty.models.utils.types.identifier import StrObjectId
 from .chain_of_thought_in_chat import ChainOfThoughtInChatTrigger
 from .chatty_ai_mode import ChattyAIMode
+from .statuses import DataCollectionStatus, PreQualifyStatus
 import logging
 
 logger = logging.getLogger(__name__)
@@ -98,6 +99,20 @@ class ChattyAIAgentInChat(CompanyAssetModel):
 
     events: List[SimplifiedExecutionEvent] = Field(default_factory=list, description="Simplified events for UI visibility")
 
+    # Data collection status (for agents with pre_qualify.form_fields)
+    data_collection_status: Optional[DataCollectionStatus] = Field(
+        default=None,
+        description="Status of data collection. None if agent has no form_fields, "
+                    "otherwise tracks progress of data collection."
+    )
+
+    # Pre-qualification status (for agents with pre_qualify config)
+    pre_qualify_status: Optional[PreQualifyStatus] = Field(
+        default=None,
+        description="Status of pre-qualification. None if agent has no pre_qualify config, "
+                    "otherwise tracks qualification evaluation."
+    )
+
     # Preview class
     preview_class: ClassVar[type[ChattyAssetPreview]] = ChattyAssetPreview
 
@@ -106,6 +121,8 @@ class ChattyAIAgentInChat(CompanyAssetModel):
         validate_by_alias=True
     )
 
+
+
     @property
     def requires_human_intervention(self) -> bool:
         """Check if the AI agent requires human intervention"""
@@ -229,3 +246,78 @@ class ChattyAIAgentInChat(CompanyAssetModel):
         self.human_intervention = None
         self.updated_at = datetime.now(ZoneInfo("UTC"))
 
+    # Data collection methods
+    @property
+    def is_data_collection_complete(self) -> bool:
+        """Check if data collection is complete (mandatory or all)"""
+        return self.data_collection_status in [
+            DataCollectionStatus.MANDATORY_COMPLETED,
+            DataCollectionStatus.ALL_COMPLETED
+        ]
+
+    @property
+    def is_data_collection_in_progress(self) -> bool:
+        """Check if data collection is still in progress"""
+        return self.data_collection_status == DataCollectionStatus.COLLECTING
+
+    def start_data_collection(self) -> None:
+        """Start data collection (set status to COLLECTING)"""
+        self.data_collection_status = DataCollectionStatus.COLLECTING
+        self.pre_qualify_status = PreQualifyStatus.PENDING
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+
+    def complete_mandatory_data_collection(self) -> None:
+        """Mark mandatory fields as completed"""
+        self.data_collection_status = DataCollectionStatus.MANDATORY_COMPLETED
+        self.pre_qualify_status = PreQualifyStatus.EVALUATING
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+
+    def complete_all_data_collection(self) -> None:
+        """Mark all fields as completed"""
+        self.data_collection_status = DataCollectionStatus.ALL_COMPLETED
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+
+    def cancel_data_collection(self) -> None:
+        """Cancel data collection"""
+        self.data_collection_status = DataCollectionStatus.CANCELLED
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+
+    # Pre-qualification methods
+    @property
+    def is_qualified(self) -> bool:
+        """Check if user is qualified"""
+        return self.pre_qualify_status == PreQualifyStatus.QUALIFIED
+
+    @property
+    def is_unqualified(self) -> bool:
+        """Check if user is unqualified"""
+        return self.pre_qualify_status == PreQualifyStatus.UNQUALIFIED
+
+    @property
+    def is_pre_qualify_pending(self) -> bool:
+        """Check if pre-qualification is still pending"""
+        return self.pre_qualify_status in [PreQualifyStatus.PENDING, PreQualifyStatus.EVALUATING]
+
+    @property
+    def has_terminal_pre_qualify_status(self) -> bool:
+        """Check if pre-qualification has reached a terminal status"""
+        return self.pre_qualify_status in [
+            PreQualifyStatus.QUALIFIED,
+            PreQualifyStatus.UNQUALIFIED
+        ]
+
+    def mark_as_qualified(self) -> None:
+        """Mark user as qualified (met acceptance criteria)"""
+        self.pre_qualify_status = PreQualifyStatus.QUALIFIED
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+
+    def mark_as_unqualified(self) -> None:
+        """Mark user as unqualified (did NOT meet acceptance criteria)"""
+        self.pre_qualify_status = PreQualifyStatus.UNQUALIFIED
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+        self.updated_at = datetime.now(ZoneInfo("UTC"))
+
+    def cancel_data_collection(self) -> None:
+        """Cancel data collection"""
+        self.data_collection_status = DataCollectionStatus.CANCELLED
+        self.updated_at = datetime.now(ZoneInfo("UTC"))

letschatty/models/company/assets/ai_agents_v2/pre_qualify_config.py

@@ -0,0 +1,111 @@
+"""
+Pre-qualification configuration for AI agents.
+
+Defines the data collection, acceptance criteria, and destination actions
+for qualifying/disqualifying users.
+"""
+
+from pydantic import BaseModel, Field
+from typing import Optional, List
+from enum import StrEnum
+from letschatty.models.utils.types.identifier import StrObjectId
+
+
+class PreQualifyDestination(StrEnum):
+    """
+    Destination/action when pre-qualification reaches a terminal state.
+    """
+    SUBSCRIBE_TO_LAUNCH = "subscribe_to_launch"  # Subscribe to launch + welcome kit
+    CALENDAR_SCHEDULER = "calendar_scheduler"    # Allow AI agent to schedule meetings
+    ESCALATE = "escalate"                        # Escalate to human
+    CUSTOM_MESSAGE = "custom_message"            # Send a custom message
+    CONTINUE = "continue"                        # Continue normal AI agent flow
+    NONE = "none"                                # Do nothing
+
+
+class PreQualifyFormField(BaseModel):
+    """
+    Form field reference with required flag.
+    The required flag is specific to this pre-qualify config, not the form field itself.
+    """
+    field_key: str = Field(description="The field_key of the FormField")
+    required: bool = Field(default=False, description="Whether this field is required for pre-qualification")
+
+
+class PreQualifyConfig(BaseModel):
+    """
+    Configuration for pre-qualification process.
+    Embedded in ChattyAIAgent.
+    """
+    # Form fields to collect (with required flag per field)
+    form_fields: List[PreQualifyFormField] = Field(
+        default_factory=list,
+        description="List of form fields to collect with their required status"
+    )
+
+    # Acceptance criteria
+    acceptance_criteria: str = Field(
+        default="",
+        description="Description of criteria for AI to evaluate if user qualifies. Empty = no criteria (auto-qualify on mandatory completion)"
+    )
+
+    # On qualified actions
+    on_qualified_destination: PreQualifyDestination = Field(
+        default=PreQualifyDestination.CONTINUE,
+        description="Action when user qualifies"
+    )
+    on_qualified_message: Optional[str] = Field(
+        default=None,
+        description="Custom message to send when user qualifies (if destination is custom_message)"
+    )
+
+    # On unqualified actions
+    on_unqualified_destination: PreQualifyDestination = Field(
+        default=PreQualifyDestination.NONE,
+        description="Action when user does NOT qualify"
+    )
+    on_unqualified_message: Optional[str] = Field(
+        default=None,
+        description="Custom message to send when user does NOT qualify (if destination is custom_message or escalate)"
+    )
+
+    @property
+    def has_form_fields(self) -> bool:
+        """Check if pre-qualify has form fields configured"""
+        return len(self.form_fields) > 0
+
+    @property
+    def has_acceptance_criteria(self) -> bool:
+        """Check if acceptance criteria is configured"""
+        return bool(self.acceptance_criteria.strip())
+
+    @property
+    def is_configured(self) -> bool:
+        """Check if pre-qualify is configured (has form fields)"""
+        return self.has_form_fields
+
+    def get_field_keys(self) -> List[str]:
+        """Get list of all field_keys"""
+        return [f.field_key for f in self.form_fields]
+
+    def get_required_field_keys(self) -> List[str]:
+        """Get list of required field_keys"""
+        return [f.field_key for f in self.form_fields if f.required]
+
+    def get_optional_field_keys(self) -> List[str]:
+        """Get list of optional field_keys"""
+        return [f.field_key for f in self.form_fields if not f.required]
+
+    def is_field_required(self, field_key: str) -> bool:
+        """Check if a specific field is required"""
+        for f in self.form_fields:
+            if f.field_key == field_key:
+                return f.required
+        return False
+
+    def remove_field(self, field_key: str) -> bool:
+        """Remove a field from the config. Returns True if field was found and removed."""
+        original_len = len(self.form_fields)
+        self.form_fields = [f for f in self.form_fields if f.field_key != field_key]
+        return len(self.form_fields) < original_len
+

letschatty/models/company/assets/ai_agents_v2/statuses.py

@@ -0,0 +1,33 @@
+from enum import StrEnum
+
+
+class DataCollectionStatus(StrEnum):
+    """
+    Status of data collection for the AI agent in this chat.
+    Only tracks field collection, not qualification status.
+
+    - COLLECTING: Still collecting data from the user
+    - MANDATORY_COMPLETED: All mandatory fields have been collected
+    - ALL_COMPLETED: All fields (mandatory + optional) have been collected
+    - CANCELLED: Data collection was cancelled
+    """
+    COLLECTING = "collecting"
+    MANDATORY_COMPLETED = "mandatory_completed"
+    ALL_COMPLETED = "all_completed"
+    CANCELLED = "cancelled"
+
+
+class PreQualifyStatus(StrEnum):
+    """
+    Status of pre-qualification for the AI agent in this chat.
+    Separate from data collection - tracks qualification evaluation.
+
+    - PENDING: Waiting for data collection to complete
+    - EVALUATING: Data collected, evaluating acceptance criteria
+    - QUALIFIED: User met acceptance criteria
+    - UNQUALIFIED: User did NOT meet acceptance criteria
+    """
+    PENDING = "pending"
+    EVALUATING = "evaluating"
+    QUALIFIED = "qualified"
+    UNQUALIFIED = "unqualified"

letschatty/models/company/assets/assignment/__init__.py

@@ -0,0 +1,14 @@
+from .assignment_assets import (
+    AssignmentStrategy,
+    AssignmentRoom,
+    AssignmentConfig,
+    AssignmentLogEntry,
+)
+
+__all__ = [
+    "AssignmentStrategy",
+    "AssignmentRoom",
+    "AssignmentConfig",
+    "AssignmentLogEntry",
+]
+

letschatty/models/company/assets/assignment/assignment_assets.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, ClassVar, Dict, Optional
+
+from pydantic import ConfigDict, Field
+
+from ....base_models.chatty_asset_model import CompanyAssetModel
+from ....utils.types.identifier import StrObjectId
+from ....utils.types.serializer_type import SerializerType
+
+
+class AssignmentStrategy(StrEnum):
+    """Assignment strategy types."""
+
+    ROUND_ROBIN = "ROUND_ROBIN"
+
+
+class AssignmentRoom(CompanyAssetModel):
+    """Scope identifier for assignment configuration, rooms and logs."""
+
+    COLLECTION: ClassVar[str] = "assignment_room"
+
+    funnel_id: Optional[StrObjectId] = Field(default=None, alias="funnelId")
+    area_id: Optional[StrObjectId] = Field(default=None, alias="areaId")
+    strategy: AssignmentStrategy = Field(default=AssignmentStrategy.ROUND_ROBIN)
+    state: Dict[str, Any] = Field(default_factory=dict)
+
+    exclude_fields = {
+        SerializerType.FRONTEND_ASSET_PREVIEW: {"state"},
+    }
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        populate_by_name=True,
+    )
+
+
+class AssignmentConfig(CompanyAssetModel):
+    """Assignment configuration document stored in MongoDB."""
+
+    COLLECTION: ClassVar[str] = "assignment_config"
+
+    funnel_id: Optional[StrObjectId] = Field(default=None, alias="funnelId")
+    area_id: Optional[StrObjectId] = Field(default=None, alias="areaId")
+    strategy: AssignmentStrategy = Field(default=AssignmentStrategy.ROUND_ROBIN)
+    params: Dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        populate_by_name=True,
+    )
+
+
+class AssignmentLogEntry(CompanyAssetModel):
+    """Immutable record inserted into assignment_log_entry collection."""
+
+    COLLECTION: ClassVar[str] = "assignment_log_entry"
+
+    chat_id: StrObjectId = Field(alias="chatId")
+    agent_id: StrObjectId = Field(alias="agentId")
+    strategy: AssignmentStrategy
+    room: AssignmentRoom
+
+    exclude_fields = {
+        SerializerType.FRONTEND_ASSET_PREVIEW: {"room"},
+    }
+
+    model_config = ConfigDict(
+        validate_by_name=True,
+        validate_by_alias=True,
+        populate_by_name=True,
+    )

letschatty/models/company/assets/automation.py

@@ -14,27 +14,18 @@ class Automation(BaseModel):
     chatty_ai_agent_config: Optional[ChattyAIConfigForAutomation] = Field(default=None)
     area: Optional[Area] = Field(default=None)
     agent_id: Optional[StrObjectId] = Field(default=None)
-    chain_of_thought : Optional[str] = Field(default=None)
+    chain_of_thought: Optional[str] = Field(default=None)
+    # Funnel transition automations
+    target_funnel_id: Optional[StrObjectId] = Field(
+        default=None,
+        description="Target funnel to move the chat to (for cross-funnel transitions)"
+    )
+    target_stage_id: Optional[StrObjectId] = Field(
+        default=None,
+        description="Target stage within the target funnel"
+    )
     # client_info: Optional[ClientInfo] = Field(default=None) me gustaría que levante el mail y/o otros atributos
 
-    @property
-    def has_automation(self) -> bool:
-        """
-        Check if there's an actual automation defined (tags, products, or flow).
-
-        Returns:
-            bool: True if there's at least one tag, product, or flow defined
-        """
-        return (
-            len(self.tags) > 0 or
-            len(self.products) > 0 or
-            len(self.flow) > 0 or
-            self.quality_score is not None or
-            self.chatty_ai_agent_config is not None or
-            self.area is not None or
-            self.highlight_description is not None
-        )
-
     @model_validator(mode='after')
     def check_agent_id(self):
         if self.area == Area.WITH_AGENT and not self.agent_id:

letschatty/models/company/assets/chat_assets.py

@@ -4,12 +4,13 @@ from enum import StrEnum
 from pydantic_core.core_schema import str_schema
 
 from letschatty.models.company.assets.ai_agents_v2.chain_of_thought_in_chat import ChainOfThoughtInChatTrigger
+from letschatty.models.company.assets.ai_agents_v2.statuses import DataCollectionStatus, PreQualifyStatus
 from ...utils.types.identifier import StrObjectId
 from datetime import datetime
 from zoneinfo import ZoneInfo
 from bson import ObjectId
 import json
-from typing import Dict, Any, Optional
+from typing import Dict, Any, Optional, List
 from letschatty.models.utils.types.serializer_type import SerializerType
 from letschatty.models.company.assets.ai_agents_v2.chatty_ai_mode import ChattyAIMode
 
@@ -66,7 +67,8 @@ class AssignedAssetToChat(BaseModel):
 
 
 class SaleAssignedToChat(AssignedAssetToChat):
-    product_id: StrObjectId = Field(frozen=True)
+    product_id: Optional[StrObjectId] = Field(default=None)
+    product_ids: List[StrObjectId] = Field(default_factory=list)
 
 class ContactPointAssignedToChat(AssignedAssetToChat):
     source_id: StrObjectId = Field(frozen=True)
@@ -75,6 +77,14 @@ class ChattyAIAgentAssignedToChat(AssignedAssetToChat):
     mode: ChattyAIMode = Field(default=ChattyAIMode.OFF)
     requires_human_intervention: bool = Field(default=False)
     is_processing: bool = Field(default=False)
+    data_collection_status: Optional[DataCollectionStatus] = Field(
+        default=None,
+        description="Status of data collection for pre-qualification"
+    )
+    pre_qualify_status: Optional[PreQualifyStatus] = Field(
+        default=None,
+        description="Status of pre-qualification"
+    )
     last_call_started_at: Optional[datetime] = Field(default=None, description="The timestamp of the get chat with prompt (the moment n8n started processing the call)")
     trigger_timestamp: Optional[datetime] = Field(default=None, description="The timestamp of the trigger that started the call, if it's a manual trigger, it will be the timestamp of the manual trigger, if it's a follow up, it will be the timestamp of the follow up, if it's a user message, it will be the timestamp of the user message")
     last_call_cot_id: Optional[StrObjectId] = Field(default=None)

letschatty/models/company/assets/company_assets.py

@@ -5,6 +5,8 @@ class CompanyAssetType(StrEnum):
     USERS = "users"
     BUSINESS_AREAS = "business_areas"
     FUNNELS = "funnels"
+    FUNNEL_STAGES = "funnel_stages"
+    FUNNEL_MEMBERS = "funnel_members"
     PRODUCTS = "products"
     SALES = "sales"
     TAGS = "tags"
@@ -20,6 +22,7 @@ class CompanyAssetType(StrEnum):
     WORKFLOWS = "workflows"
     CHATTY_AI_AGENTS = "chatty_ai_agents"
     FILTER_CRITERIA = "filter_criteria"
+    FORM_FIELDS = "form_fields"
 
     @classmethod
     def get_all(cls) -> List[str]:

letschatty/models/company/assets/launch/__init__.py

@@ -0,0 +1,12 @@
+from .launch import Launch, LaunchStatus
+from .scheduled_communication import LaunchScheduledCommunication
+from .subscription import LaunchSubscription, LaunchSubscriptionStatus
+
+__all__ = [
+    'Launch',
+    'LaunchStatus',
+    'LaunchScheduledCommunication',
+    'LaunchSubscription',
+    'LaunchSubscriptionStatus'
+]
+

letschatty/models/company/assets/launch/launch.py

@@ -0,0 +1,128 @@
+from pydantic import Field
+from typing import List, Optional
+from datetime import datetime
+from enum import StrEnum
+from letschatty.models.base_models.chatty_asset_model import CompanyAssetModel
+from letschatty.models.utils.types.identifier import StrObjectId
+from .scheduled_communication import LaunchScheduledCommunication
+from .subscription import LaunchSubscription, LaunchSubscriptionStatus
+from urllib.parse import urlparse, urlunparse, parse_qs, urlencode
+
+
+class LaunchStatus(StrEnum):
+    """Status of the launch"""
+    DRAFT = "draft"
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+
+
+class Launch(CompanyAssetModel):
+    """
+    Launch asset model.
+    Represents a product launch event with communications and subscriptions.
+    """
+    # Basic info
+    name: str = Field(description="Name of the launch")
+    product_name: str = Field(description="Name of the product being launched")
+    product_description: str = Field(description="Description of the product being launched")
+    launch_datetime: datetime = Field(description="Date and time of the launch")
+    access_link: str = Field(description="Base link for the launch event")
+    status: LaunchStatus = Field(default=LaunchStatus.DRAFT, description="Current status of the launch")
+
+    # Data Collection & Pre-qualification
+    form_fields: List[StrObjectId] = Field(
+        default_factory=list,
+        description="FormField IDs required before subscription"
+    )
+    acceptance_criteria: str = Field(
+        default="",
+        description="Instructions for AI to determine when to subscribe the user"
+    )
+    enable_tracking: bool = Field(
+        default=False,
+        description="If True, generate personal trackable links for each subscriber"
+    )
+
+    # Communications
+    welcome_kit: Optional[LaunchScheduledCommunication] = Field(
+        default=None,
+        description="Communication sent immediately upon subscription (delta_minutes=0)"
+    )
+    pre_launch_communications: List[LaunchScheduledCommunication] = Field(
+        default_factory=list,
+        description="Communications scheduled before the launch"
+    )
+    post_launch_attended_communications: List[LaunchScheduledCommunication] = Field(
+        default_factory=list,
+        description="Communications for attendees after the launch"
+    )
+    post_launch_missed_communications: List[LaunchScheduledCommunication] = Field(
+        default_factory=list,
+        description="Communications for those who missed the launch"
+    )
+
+    # Subscriptions (embedded)
+    subscriptions: List[LaunchSubscription] = Field(
+        default_factory=list,
+        description="List of chat subscriptions to this launch"
+    )
+
+    # AI Configuration
+    chat_examples: List[StrObjectId] = Field(
+        default_factory=list,
+        description="Chat examples for AI message adaptation"
+    )
+    contexts: List[StrObjectId] = Field(
+        default_factory=list,
+        description="Specific contexts for the launch"
+    )
+
+    @property
+    def all_communications(self) -> List[LaunchScheduledCommunication]:
+        """Get all communications including welcome kit"""
+        comms = []
+        if self.welcome_kit:
+            comms.append(self.welcome_kit)
+        comms.extend(self.pre_launch_communications)
+        comms.extend(self.post_launch_attended_communications)
+        comms.extend(self.post_launch_missed_communications)
+        return comms
+
+    def get_subscription_by_chat_id(self, chat_id: StrObjectId) -> Optional[LaunchSubscription]:
+        """Find a subscription by chat ID"""
+        for sub in self.subscriptions:
+            if str(sub.chat_id) == str(chat_id):
+                return sub
+        return None
+
+    def is_chat_subscribed(self, chat_id: StrObjectId) -> bool:
+        """Check if a chat is subscribed to this launch"""
+        sub = self.get_subscription_by_chat_id(chat_id)
+        return sub is not None and sub.status in [
+            LaunchSubscriptionStatus.SUBSCRIBED,
+            LaunchSubscriptionStatus.ATTENDED
+        ]
+
+    def get_access_link_for_subscriber(self, chat_id: StrObjectId) -> str:
+        """
+        Returns the personal trackable link for a subscriber if tracking is enabled,
+        otherwise returns the general access_link.
+        """
+        if self.enable_tracking:
+            subscription = self.get_subscription_by_chat_id(chat_id)
+            if subscription and subscription.personal_access_link:
+                return subscription.personal_access_link
+        return self.access_link
+
+    def generate_personal_link(self, chat_id: StrObjectId) -> str:
+        """
+        Generates a unique trackable link for a given chat_id.
+        Adds a 'subscriber' query parameter to the base access_link.
+        """
+        parsed_url = urlparse(self.access_link)
+        query_params = parse_qs(parsed_url.query)
+        query_params['subscriber'] = [str(chat_id)]
+        new_query = urlencode(query_params, doseq=True)
+        return urlunparse(parsed_url._replace(query=new_query))
+

letschatty/models/company/assets/launch/scheduled_communication.py

@@ -0,0 +1,44 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+from datetime import datetime
+from letschatty.models.messages.chatty_messages.base.message_draft import MessageDraft
+from letschatty.models.company.assets.ai_agents_v2.ai_agent_message_draft import AIAgentMessageDraft
+
+
+class LaunchScheduledCommunication(BaseModel):
+    """
+    Scheduled communication for pre/post launch.
+    Can be AI-adapted or literal messages.
+    """
+    id: str = Field(description="Unique identifier for the communication")
+    name: str = Field(description="Name of the communication (e.g., '5 dias antes', '2 horas antes')")
+    delta_minutes: int = Field(
+        description="Minutes relative to the launch (negative=before, positive=after, 0=welcome kit)"
+    )
+
+    # Content - one or the other
+    ai_communication: Optional[AIAgentMessageDraft] = Field(
+        default=None,
+        description="AI adapted communication content and instructions"
+    )
+    literal_messages: Optional[List[MessageDraft]] = Field(
+        default=None,
+        description="Literal messages to be sent without AI adaptation"
+    )
+
+    # State
+    sent_at: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp when this communication was sent globally for the launch"
+    )
+
+    @property
+    def requires_ai(self) -> bool:
+        """Check if this communication requires AI adaptation"""
+        return self.ai_communication is not None
+
+    @property
+    def is_sent(self) -> bool:
+        """Check if this communication has been sent"""
+        return self.sent_at is not None
+