ChatBotHelper Model

class smarter.apps.chatbot.models.ChatBotHelper(request, *args, **kwargs)[source]

Bases: SmarterRequestMixin

Provides a mapping between URLs and their corresponding ChatBot models, abstracting URL parsing logic for reuse across the codebase.

This helper class is designed to centralize and standardize the logic required to resolve a ChatBot instance from a given URL or request context. It is intended for use in various locations, including within this module, Django middleware, and view logic.

The class also implements caching of ChatBot objects for specific URLs, reducing redundant parsing and database queries for repeated requests.

Supported URL Patterns

The following are examples of valid URLs that this helper can process:

  • Authentication Optional URLs:

    • https://example-username.3141-5926-5359.alpha.api.example.com/

    • https://example-username.3141-5926-5359.alpha.api.example.com/config/

  • Authenticated URLs:

    • https://alpha.api.example-username.com/smarter/example/

    • https://example-username.smarter.sh/chatbot/

    • https://alpha.api.example-username.com/workbench/1/

    • https://alpha.api.example-username.com/workbench/example/

  • Legacy (pre v0.12) URLs:

    • https://alpha.api.example-username.com/chatbots/1/

    • https://alpha.api.example-username.com/chatbots/example/

where for example-username, example is the ChatBot name, username is the Account Username, and 3141-5926-5359 is the Account Number.

Features

  • Abstracts and encapsulates URL parsing and ChatBot resolution logic.

  • Provides a consistent interface for retrieving ChatBot instances from URLs.

  • Caches ChatBot objects to avoid redundant lookups.

  • Supports both authenticated and unauthenticated URL patterns.

  • Handles legacy URL formats for backward compatibility.

Usage

This class is typically instantiated with a Django HttpRequest object. It can then be used to access the resolved ChatBot instance and related metadata, such as the associated account, chatbot ID, and custom domain.

Example:

helper = ChatBotHelper(request)
chatbot = helper.chatbot
if helper.is_valid:
    # Proceed with chatbot logic
Parameters:

  • request (django.http.HttpRequest) – The Django HttpRequest object containing the URL and user context.

  • args – Additional positional arguments.

  • kwargs – Additional keyword arguments, such as ‘chatbot’, ‘chatbot_custom_domain’, etc.

Raises:

SmarterConfigurationError – If the helper cannot resolve a valid ChatBot instance.

Note

This class is intended for internal use within the Smarter platform and should not be used directly in user-facing code without proper validation.

__init__(request, *args, **kwargs)[source]

Initializes the ChatBotHelper instance.

Parameters:

  • request (django.http.HttpRequest) – The Django HttpRequest object.

  • args – Additional positional arguments.

  • kwargs – Additional keyword arguments.

property account: Account | None[source]

Return the associated Account for this ChatBotHelper instance, optionally overriding the default account based on the account number parsed from the URL, if available.

If the URL contains an account number (for example, http://education.3141-5926-5359.api.localhost:9357/config/), this method will attempt to retrieve and return the corresponding cached Account object. If no account number is found in the URL, the default account from the superclass is returned.

Returns:

The resolved Account instance, or None if not found.

Return type:

Optional[Account]

property api_host: str | None[source]

Returns the API host for a ChatBot API URL.

This property extracts and returns the API host component from the chatbot URL, supporting named, sandbox, and custom domain URLs.

Examples

Named URL:

  • https://hr.3141-5926-5359.alpha.api.example.com/chatbot/ returns 'alpha.api.example.com'

Sandbox URL:

  • http://api.localhost:9357/api/v1/chatbots/1/chat/ returns 'api.localhost:9357'

Custom domain URL:

  • https://hr.smarter.sh/chatbot/ returns 'hr.smarter.sh'

Returns:

The API host as a string, or None if not found.

Return type:

Optional[str]

property chatbot: ChatBot | None

Returns a lazy instance of the ChatBot.

Examples

Returns:

The ChatBot instance, or None if not found.

Return type:

Optional[ChatBot]

property chatbot_custom_domain: ChatBotCustomDomain | None

Returns a lazy instance of the ChatBotCustomDomain.

Examples

  • https://hr.smarter.sh/chatbot/ returns ChatBotCustomDomain(domain_name='smarter.sh')

Returns:

The ChatBotCustomDomain instance, or None if not found.

Return type:

Optional[ChatBotCustomDomain]

property chatbot_id: int | None

Returns the ChatBot.id for this ChatBotHelper instance.

This property attempts to resolve the ChatBot’s unique integer ID using several strategies:

  1. If a chatbot ID was provided at initialization, it is returned immediately.

  2. If a ChatBot object is already cached, its ID is returned.

  3. If the parent SmarterRequestMixin provides a chatbot ID (e.g., parsed from the URL), it is used.

  4. If both a chatbot name and account are available, attempts to resolve and cache the ChatBot object and its ID.

Returns:

The resolved ChatBot ID, or None if not found.

Return type:

Optional[int]

property chatbot_name: str | None

Returns the ChatBot.name for the ChatBotHelper.

property chatbot_plugins_list: list[ChatBotPlugin]

Returns a list of ChatBotPlugin instances associated with the ChatBot.

Returns:

A list of ChatBotPlugin instances.

Return type:

list[ChatBotPlugin]

property chatbot_plugins_list_str: str[source]

Returns a comma-separated string of ChatBotPlugin names associated with the ChatBot.

Returns:

A comma-separated string of ChatBotPlugin names.

Return type:

str

property chatbothelper_ready_state: str

Returns a formatted string indicating whether the ChatBotHelper is ready.

Returns:

A string indicating whether the ChatBotHelper is ready or not.

property formatted_class_name: str[source]

Get the formatted class name for this instance of ChatBotHelper.

Returns:

The formatted class name as a string, including the parent class name.

Return type:

str

This property returns a string representation of the class name, formatted to include the parent class’s formatted name and the ChatBotHelper class. This is useful for logging and debugging purposes, as it provides a clear and consistent identifier for instances of this helper class.

Example

>>> helper = ChatBotHelper(request)
>>> helper.formatted_class_name
'smarter.apps.chatbot.models.ChatBotHelper()'
property is_authentication_required: bool[source]

Determines if authentication is required to access the ChatBot.

Returns:

True if authentication is required, otherwise False.

Return type:

bool

property is_chatbothelper_ready: bool[source]

Returns True if the ChatBotHelper is ready to be used.

This is a convenience property that checks if the ChatBotHelper is initialized and has a valid ChatBot instance.

Returns:

True if the helper is initialized and has a valid ChatBot, otherwise False.

Return type:

bool

property is_custom_domain: bool

Returns True if the ChatBot is using a custom domain.

Returns:

True if a custom domain is configured, otherwise False.

Return type:

bool

property is_deployed: bool
property name: str | None

Returns the name of the chatbot.

This property attempts to resolve the chatbot’s name using several strategies, in order of precedence:

  1. self._name: The name assigned during initialization, if available.

  2. self.chatbot.name: The name attribute of the resolved ChatBot instance, if present.

  3. self.subdomain: If the URL is a named chatbot URL (i.e., is_chatbot_named_url is True), the subdomain is used as the name.

  4. Path slug: If the URL is a sandbox chatbot URL (i.e., is_chatbot_sandbox_url is True), the path slug is used as the name.

Returns:

The resolved chatbot name, or None if not found.

Return type:

Optional[str]

property provider: Provider | None[source]

Returns the Provider associated with the ChatBot.

Returns:

The Provider instance, or None if not found.

Return type:

Optional[Provider]

property ready: bool

Returns True if the ChatBotHelper and its ChatBot are ready to be used. This property checks both the readiness of the ChatBotHelper itself and the readiness of the underlying ChatBot instance.

Returns:

True if both the helper and ChatBot are ready, otherwise False.

Return type:

bool

property rfc1034_compliant_name: str | None

Returns a URL-friendly name for the chatbot.

This is a convenience property that returns a RFC 1034 compliant name for the chatbot.

Examples

self.name  # 'Example ChatBot 1'
self.rfc1034_compliant_name  # 'example-chatbot-1'
Returns:

The RFC 1034 compliant name for the chatbot, or None if not available.

Return type:

Optional[str]

to_json()[source]

Serialize the ChatBotHelper to a dictionary.

This method returns a dictionary representation of the ChatBotHelper instance, including key metadata and related objects such as the chatbot, account, and custom domain.

Returns:

A dictionary containing the serialized state of the ChatBotHelper.

Return type:

dict[str, Any]