ChatBot Model

class smarter.apps.chatbot.models.ChatBot(*args, **kwargs)[source]

Bases: MetaDataWithOwnershipModel

Implements the ChatBot API model for a customer account.

This Django model represents a chatbot instance associated with a specific customer account. It provides configuration, deployment status, domain management, and API endpoint properties for each chatbot. The model supports multiple modes of operation (sandbox, custom, default), DNS verification, TLS certificate management, and integration with external providers.

Key Features

Associates each chatbot with a customer Account.
Supports custom domains and DNS verification via ChatBotCustomDomain.
Tracks deployment status, TLS certificate issuance, and DNS verification.
Configures default provider, model, system role, temperature, and max tokens.
Provides properties for generating RFC 1034-compliant names, hosts, and URLs.
Supports sandbox, default, and custom domain modes.
Integrates with Django signals for deployment and verification events.
Serializes chatbot configuration for API and frontend consumption.

Usage Example

chatbot = ChatBot.objects.get(account=my_account, name="example")
if chatbot.ready():
    print(chatbot.url_chatbot)

Signals

Emits signals on deployment, DNS verification, and certificate status changes.

See Also

Raises:

SmarterValueError – If invalid URLs or domains are provided.
ValidationError – If provider is not valid.

Parameters:

id (BigAutoField) – Primary key: ID
created_at (DateTimeField) – Created at
updated_at (DateTimeField) – Updated at
name (CharField) –
Name. Name in camelCase, e.g., ‘apiKey’, no special characters.

The name of the function available to the ChatBot. Example: “weather”
description (TextField) – Description. A brief description of this resource. Be verbose, but not too verbose.
version (CharField) – Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.
annotations (JSONField) – Annotations. Key-value pairs for annotating this resource.
deployed (BooleanField) –
Deployed

Indicates whether the ChatBot is deployed and accessible via its custom or default domain. Modifying this value triggers asynchronous deployment or undeployment processes. Example: True
provider (CharField) –
Provider

The Smarter Provider for the ChatBot’s language model. Example: “openai”
default_model (CharField) –
Default model

The default language model used by the ChatBot. Example: “gpt-4o-mini”
default_system_role (TextField) –
Default system role

The default system role prompt for the ChatBot. Example: “You are a helpful assistant.”
default_temperature (FloatField) –
Default temperature

The default temperature setting for the ChatBot’s language model. Example: 0.7
default_max_tokens (IntegerField) –
Default max tokens

The default maximum tokens for the ChatBot’s language model responses. Example: 1024
app_name (CharField) –
App name

The ChatBot UI configuration fields. Appears in the title bar of the Smarter React ChatBot component. Example: “Stackademy Support Bot”
app_assistant (CharField) –
App assistant

The ChatBot UI configuration fields. Appears in the text input area placeholder. Example: “Stan”
app_welcome_message (CharField) –
App welcome message

The ChatBot UI configuration fields. Appears in the welcome message area of the Smarter React ChatBot component. Example: “Welcome to Stackademy!”
app_example_prompts (JSONField) –
App example prompts

The ChatBot UI configuration fields. Example prompts shown to the user in the Smarter React ChatBot component. Example: [“What AI courses do you offer?”, “Is your program free?”]
app_placeholder (CharField) –
App placeholder

The ChatBot UI configuration fields. Placeholder text in the chat input area. Example: “Ask me anything about Stackademy…”
app_info_url (URLField) –
App info url

The ChatBot UI configuration fields. URL to the app information button in the top-right of the Smarter React ChatBot component. Example: “https://smarter.sh”
app_background_image_url (URLField) –
App background image url

The ChatBot UI configuration fields. URL to the app background image in the Smarter React ChatBot component. Example: “https://cdn.smarter.sh/chat-ui/background.png”
app_logo_url (URLField) –
App logo url

The ChatBot UI configuration fields. URL to the app logo image in the Smarter React ChatBot component. Example: “https://cdn.smarter.sh/chat-ui/logo.png”
app_file_attachment (BooleanField) –
App file attachment

The ChatBot UI configuration fields. Enables or disables file attachment feature in the Smarter React ChatBot component. Example: True
dns_verification_status (CharField) – Dns verification status
tls_certificate_issuance_status (CharField) – Tls certificate issuance status

Relationship fields:

Parameters:

user_profile (ForeignKey to UserProfile) – User profile (related name: chatbots)
subdomain (ForeignKey to ChatBotCustomDomainDNS) –
Subdomain (related name: chatbot)

The subdomain DNS record associated with this ChatBot. Example: ChatBotCustomDomainDNS(id=1, domain=”my-chatbot.example.com”)
custom_domain (ForeignKey to ChatBotCustomDomain) –
Custom domain (related name: chatbot)

The custom domain associated with this ChatBot. Example: ChatBotCustomDomain(id=1, domain=”example.com”)
tags (TaggableManager to Tag) – Tags. Tags for categorizing and organizing this resource. (related name: chatbot)
tagged_items (GenericRelation to TaggedItem) – Tagged items (related name: +)

Reverse relationships:

Parameters:

chatbotapikey (Reverse ForeignKey from ChatBotAPIKey) – All ChatBot API Keys of this chat bot (related name of chatbot)
chatbotplugin (Reverse ForeignKey from ChatBotPlugin) – All ChatBot Plugins of this chat bot (related name of chatbot)
chatbotfunctions (Reverse ForeignKey from ChatBotFunctions) – All ChatBot Functions of this chat bot (related name of chatbot)
chatbotrequests (Reverse ForeignKey from ChatBotRequests) – All ChatBot Requests History of this chat bot (related name of chatbot)
chat (Reverse ForeignKey from Chat) – All Chats of this chat bot (related name of chatbot)

class DnsVerificationStatusChoices(*values)[source]

Bases: TextChoices

DNS Verification Status Choices for ChatBot Custom Domains. This is managed by the asynchronous ChatBot deployment process.

FAILED = 'Failed'

NOT_VERIFIED = 'Not Verified'

VERIFIED = 'Verified'

VERIFYING = 'Verifying'

exception DoesNotExist: Bases: ObjectDoesNotExist

class Modes[source]

Bases: object

ChatBot API Modes. Defines the operational mode of the ChatBot instance. Also affects the url scheme and hostname used to access the ChatBot API.

CUSTOM = 'custom'

DEFAULT = 'default'

SANDBOX = 'sandbox'

UNKNOWN = 'unknown'

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

class Schemes[source]

Bases: object

ChatBot API Schemes

HTTP = 'http'

HTTPS = 'https'

class TlsCertificateIssuanceStatusChoices(*values)[source]

Bases: TextChoices

TLS Certificate Issuance Status Choices for ChatBot Custom Domains. This is managed by the asynchronous ChatBot deployment process.

FAILED = 'Failed'

ISSUED = 'Issued'

NO_CERTIFICATE = 'No Certificate'

REQUESTED = 'Requested'

annotations

JSONField

Annotations. Key-value pairs for annotating this resource.

Type:: Type

app_assistant

CharField

App assistant

The ChatBot UI configuration fields. Appears in the text input area placeholder. Example: “Stan”

Type:: Type

app_background_image_url

URLField

App background image url

The ChatBot UI configuration fields. URL to the app background image in the Smarter React ChatBot component. Example: “https://cdn.smarter.sh/chat-ui/background.png”

Type:: Type

app_example_prompts

JSONField

App example prompts

The ChatBot UI configuration fields. Example prompts shown to the user in the Smarter React ChatBot component. Example: [“What AI courses do you offer?”, “Is your program free?”]

Type:: Type

app_file_attachment

BooleanField

App file attachment

The ChatBot UI configuration fields. Enables or disables file attachment feature in the Smarter React ChatBot component. Example: True

Type:: Type

app_info_url

URLField

App info url

The ChatBot UI configuration fields. URL to the app information button in the top-right of the Smarter React ChatBot component. Example: “https://smarter.sh”

Type:: Type

app_logo_url

URLField

App logo url

The ChatBot UI configuration fields. URL to the app logo image in the Smarter React ChatBot component. Example: “https://cdn.smarter.sh/chat-ui/logo.png”

Type:: Type

app_name

CharField

App name

The ChatBot UI configuration fields. Appears in the title bar of the Smarter React ChatBot component. Example: “Stackademy Support Bot”

Type:: Type

app_placeholder

CharField

App placeholder

The ChatBot UI configuration fields. Placeholder text in the chat input area. Example: “Ask me anything about Stackademy…”

Type:: Type

app_welcome_message

CharField

App welcome message

The ChatBot UI configuration fields. Appears in the welcome message area of the Smarter React ChatBot component. Example: “Welcome to Stackademy!”

Type:: Type

property base_api_domain

The base API domain for the ChatBot. This is the domain that is used in the default hostname for the ChatBot.

Examples

example 1. given:

environment is “alpha”
environment API domain “alpha.api.example.com”

the resulting base API domain would be: ‘alpha.api.example.com’

example 2. given:

environment is “local”
environment API domain “api.localhost:9357”

the resulting base API domain would be: ‘api.local.example.com’

property base_default_host

The base default hostname for the ChatBot. This is the part of the hostname that comes after the RFC 1034 compliant name. It includes the account number and the environment API domain.

Examples

example 1. given:

a ChatBot associated with an account number “1234-5678-9012”
environment is “alpha”
environment API domain “alpha.api.example.com”

the resulting base default host would be: ‘.1234-5678-9012.alpha.api.example.com’

example 2. given:

a ChatBot associated with an account number “1234-5678-9012”
environment is “local”
environment API domain “api.localhost:9357”

the resulting base default host would be: ‘.1234-5678-9012.api.local.example.com’

chat_set

Reverse ForeignKey from Chat

All Chats of this chat bot (related name of chatbot)

Type:: Type

chatbotapikey_set

Reverse ForeignKey from ChatBotAPIKey

All ChatBot API Keys of this chat bot (related name of chatbot)

Type:: Type

chatbotfunctions_set

Reverse ForeignKey from ChatBotFunctions

All ChatBot Functions of this chat bot (related name of chatbot)

Type:: Type

chatbotplugin_set

Reverse ForeignKey from ChatBotPlugin

All ChatBot Plugins of this chat bot (related name of chatbot)

Type:: Type

chatbotrequests_set

Reverse ForeignKey from ChatBotRequests

All ChatBot Requests History of this chat bot (related name of chatbot)

Type:: Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created. This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:: Type

custom_domain

ForeignKey to ChatBotCustomDomain

Custom domain (related name: chatbot)

The custom domain associated with this ChatBot. Example: ChatBotCustomDomain(id=1, domain=”example.com”)

Type:: Type

custom_domain_id: Internal field, use custom_domain instead.

property custom_host

The custom hostname for the ChatBot.

Examples:

self.name: ‘example’
self.custom_domain.domain_name: ‘example.com’

example ‘example.example.com’

Returns:: custom hostname
Return type:: str

property custom_url

The custom URL for the ChatBot.

example ‘https://example.example.com’

Returns:: custom URL
Return type:: str

property default_host

The default hostname for the ChatBot. Examples:

example 1. given:

self.name: ‘example’
self.account.account_number: ‘1234-5678-9012’
smarter_settings.environment = “alpha”
smarter_settings.environment_api_domain: ‘alpha.api.example.com’

The domain would be: ‘example.1234-5678-9012.alpha.api.example.com’

example 2. given:

self.name: ‘example’
self.account.account_number: ‘1234-5678-9012’
smarter_settings.environment = “local”
smarter_settings.environment_api_domain: ‘api.localhost:9357’

The domain would be: ‘example.1234-5678-9012.api.local.example.com’

Returns:: default hostname
Return type:: str

default_max_tokens

IntegerField

Default max tokens

The default maximum tokens for the ChatBot’s language model responses. Example: 1024

Type:: Type

default_model

CharField

Default model

The default language model used by the ChatBot. Example: “gpt-4o-mini”

Type:: Type

default_system_role

TextField

Default system role

The default system role prompt for the ChatBot. Example: “You are a helpful assistant.”

Type:: Type

property default_system_role_enhanced

prepends a date/time string to the default_system_role

Example: “2024-06-01 12:00:00 System: You are a helpful assistant.” :returns: enhanced system role string :rtype: str

default_temperature

FloatField

Default temperature

The default temperature setting for the ChatBot’s language model. Example: 0.7

Type:: Type

property default_url

The default URL for the ChatBot.

example ‘https://example.1234-5678-9012.alpha.api.example.com’

Returns:: default URL
Return type:: str

deployed

BooleanField

Deployed

Indicates whether the ChatBot is deployed and accessible via its custom or default domain. Modifying this value triggers asynchronous deployment or undeployment processes. Example: True

Type:: Type

description

TextField

Description. A brief description of this resource. Be verbose, but not too verbose.

Type:: Type

dns_verification_status

CharField

Dns verification status

Choices:

Verifying
Not Verified
Verified
Failed

Type:: Type

classmethod get_cached_object(invalidate=False, pk=None, name=None, user=None, user_profile=None, account=None)[source]

Retrieve a model instance using caching to optimize performance.

Example usage:

# Retrieve a ChatBot instance by primary key with caching
chatbot = ChatBot.get_cached_object(pk=1)

# Retrieve a ChatBot instance by name and user profile with caching
chatbot = ChatBot.get_cached_object(name="example", user_profile=my_user_profile)

Parameters:

pk (Optional[int]) – The primary key of the model instance to retrieve.
name (Optional[str]) – The name of the model instance to retrieve.
user (Optional[User]) – The user associated with the model instance.
user_profile (Optional[UserProfile]) – The user profile associated with the model instance.
account (Optional[Account]) – The account associated with the model instance.

Returns:

The model instance if found, otherwise None.

Return type:

Optional[“ChatBot”]

classmethod get_cached_objects(invalidate=False, user_profile=None)[source]

Retrieve a list of ChatBot instances associated with a user profile using caching.

Example usage:

# Retrieve ChatBot instances for a user profile with caching
chatbots = ChatBot.get_cached_objects(my_user_profile, invalidate=True)

Parameters:

invalidate (Optional[bool]) – Whether to invalidate the cache for this retrieval.
user_profile (Optional[UserProfile]) – The user profile for which to retrieve ChatBot instances.

Returns:

A queryset of ChatBot instances associated with the user profile.

Return type:

models.QuerySet[“ChatBot”]

get_dns_verification_status_display(*, field=<django.db.models.CharField: dns_verification_status>): Shows the label of the dns_verification_status. See get_FOO_display() for more information.

get_tls_certificate_issuance_status_display(*, field=<django.db.models.CharField: tls_certificate_issuance_status>): Shows the label of the tls_certificate_issuance_status. See get_FOO_display() for more information.

property hostname

The hostname for the ChatBot depending on its deployment status. Returns either the custom hostname (if deployed), the default hostname, or the sandbox hostname.

Returns:: hostname
Return type:: str

id

BigAutoField

Primary key: ID

Type:: Type

mode(url)[source]

Determine the mode of the ChatBot based on the provided URL.

Parameters:: url (str) – The URL to evaluate.
Returns:: The mode of the ChatBot (sandbox, custom, default, unknown).
Return type:: str

name

CharField

Name. Name in camelCase, e.g., ‘apiKey’, no special characters.

Type:: Type

objects = <django.db.models.Manager object>

provider

CharField

Provider

The Smarter Provider for the ChatBot’s language model. Example: “openai”

Type:: Type

property ready

The readiness status of the ChatBot.

A ChatBot is ready if it is its in sandbox mode, or, if it is:

deployed
has a verified DNS A record
has a valid, issued tls certificate.

Returns:: readiness status
Return type:: bool

property rfc1034_compliant_name: str

Returns a RFC 1034 compliant name for the ChatBot. This name is used in the hostname of the ChatBot’s default and custom URLs. The name is constructed by combining the ChatBot’s name and the username of the associated user profile, separated by a dot. The resulting name adheres to the following rules:

lower case
alphanumeric characters and hyphens only [a-z0-9-]
starts and ends with an alphanumeric character
max length of 63 characters
no consecutive hyphens
no leading or trailing hyphens
no underscores or special characters
no spaces
no dots except for separating the ChatBot name and username
no more than one dot

Examples:

For a ChatBot with name “example” and associated user profile “adminuser”,
that IS the account admin, the resulting RFC 1034 compliant name would be “example”
For a ChatBot with name “example” and associated user profile “user123”,
that is NOT the account admin, the resulting RFC 1034 compliant name would be “example.user123”

Returns:: RFC 1034 compliant name
Return type:: str

property sandbox_host

The sandbox hostname for the ChatBot. This is the hostname that is used when the ChatBot is in sandbox mode. For example, when the ChatBot is being used in the Smarter Workbench.

example ‘alpha.platform.smarter.sh’

Returns:: sandbox hostname
Return type:: str

property sandbox_url

The sandbox URL for the ChatBot. This is the URL that is used when the ChatBot is in sandbox mode. For example, when the ChatBot is being used in the Smarter Workbench. maps to “<int:chatbot_id>/”

example: ‘https://alpha.platform.smarter.sh/workbench/chatbots/<str:hashed_id>/’

Returns:: sandbox URL
Return type:: str

save(*args, asynchronous=False, **kwargs)[source]

Override save() to validate domain and send signals on status changes.

Raises:: SmarterValueError – If invalid hostname is provided.
Args:: Positional arguments for the save method.
Asynchronous:: If True, skips signal sending for asynchronous operations.
Kwargs:: Keyword arguments for the save method.
Returns:: None

subdomain

ForeignKey to ChatBotCustomDomainDNS

Subdomain (related name: chatbot)

The subdomain DNS record associated with this ChatBot. Example: ChatBotCustomDomainDNS(id=1, domain=”my-chatbot.example.com”)

Type:: Type

subdomain_id: Internal field, use subdomain instead.

tagged_items

Reverse GenericRelation from ChatBot

All + of this tagged item (related name of tagged_items)

Type:: Type

tags = <taggit.managers._TaggableManager object>

tls_certificate_issuance_status

CharField

Tls certificate issuance status

Choices:

No Certificate
Requested
Issued
Failed

Type:: Type

updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated. This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:: Type

property url

The URL for the ChatBot depending on its deployment status.

example: ‘https://my-chatbot.1234-5678-9012.alpha.api.example.com’ (custom, deployed)

Returns:: URL
Return type:: str

property url_chat_config

The Smarter Api url for the Chat config json dict. The React.js app requests this url during react app startup to retrieve the UI configuration for the chatbot.

maps to “<int:chatbot_id>/config/” example: “http://localhost:9357/api/v1/chatbots/5174/config/”

Returns:: URL for chatbot config API
Return type:: str

property url_chatapp: str

(Deprecated) The Smarter Api url for the ChatApp endpoint. This url is used by the React.js app to load the ChatApp web page.

maps to “chat/”

property url_chatbot

The Smarter Api url returned by ChatConfigView.config() as the key, “url_chatbot”. This url is consumed by React.js app for http requests on new prompts.

maps to “<int:chatbot_id>/chat/” example: “http://localhost:9357/api/v1/chatbots/5174/chat/”

Returns:: URL for chatbot API
Return type:: str

user_profile

ForeignKey to UserProfile

User profile (related name: chatbots)

Type:: Type

user_profile_id: Internal field, use user_profile instead.

version

CharField

Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.

Type:: Type