LLMClient Model

class smarter.apps.llm_client.models.LLMClient(*args, **kwargs)[source]

Bases: MetaDataWithOwnershipModel

Implements the LLMClient API model for a customer account.

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

Key Features

Associates each llm_client with a customer Account.
Supports custom domains and DNS verification via LLMClientCustomDomain.
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 llm_client configuration for API and frontend consumption.

Usage Example

llm_client = LLMClient.objects.get(account=my_account, name="example")
if llm_client.ready():
    print(llm_client.url_llm_client)

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 (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
name (Unknown) – Name. Name in camelCase, e.g., ‘apiKey’, no special characters.
description (Unknown) – Description. A brief description of this resource. Be verbose, but not too verbose.
version (Unknown) – Version. Semantic version in the format MAJOR.MINOR.PATCH, e.g., ‘1.0.0’.
annotations (Unknown) – Annotations. Key-value pairs for annotating this resource.
deployed (Unknown) –
Deployed

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Relationship fields:

Parameters:

user_profile (Unknown) – User profile (related name: llmclient)
subdomain (Unknown) –
Subdomain (related name: llmclient)

The subdomain DNS record associated with this LLMClient. Example: LLMClientCustomDomainDNS(id=1, domain=”my-llm_client.example.com”)
custom_domain (Unknown) –
Custom domain (related name: llmclient)

The custom domain associated with this LLMClient. Example: LLMClientCustomDomain(id=1, domain=”example.com”)
tags (Unknown) – Tags. Tags for categorizing and organizing this resource. (related name: llmclient)
tagged_items (Unknown) – Tagged items (related name: +)

Reverse relationships:

Parameters:

llmclientapikey (Unknown) – All LLMClient API Keys of this llm client (related name of llm_client)
llmclientfunctions (Unknown) – All LLMClient Functions of this llm client (related name of llm_client)
llmclientplugin (Unknown) – All LLMClient Plugins of this llm client (related name of llm_client)
llmclientrequests (Unknown) – All LLMClient Requests History of this llm client (related name of llm_client)
prompt (Unknown) – All Chats of this llm client (related name of llm_client)

class DnsVerificationStatusChoices(*values)[source]

Bases: TextChoices

DNS Verification Status Choices for LLMClient Custom Domains.

This is managed by the asynchronous LLMClient deployment process.

FAILED = 'Failed'

NOT_VERIFIED = 'Not Verified'

VERIFIED = 'Verified'

VERIFYING = 'Verifying'

exception DoesNotExist: Bases: ObjectDoesNotExist

class Modes[source]

Bases: object

LLMClient API Modes.

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

CUSTOM = 'custom'

DEFAULT = 'default'

SANDBOX = 'sandbox'

UNKNOWN = 'unknown'

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

exception NotUpdated: Bases: ObjectNotUpdated, DatabaseError

class Schemes[source]

Bases: object

LLMClient API Schemes.

HTTP = 'http'

HTTPS = 'https'

class TlsCertificateIssuanceStatusChoices(*values)[source]

Bases: TextChoices

TLS Certificate Issuance Status Choices for LLMClient Custom Domains.

This is managed by the asynchronous LLMClient 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 LLMClient UI configuration fields. Appears in the text input area placeholder. Example: “Stan”

Type:: Type

app_background_image_url

URLField

App background image url

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

Type:: Type

app_example_prompts

JSONField

App example prompts

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

Type:: Type

app_file_attachment

BooleanField

App file attachment

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

Type:: Type

app_info_url

URLField

App info url

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

Type:: Type

app_logo_url

URLField

App logo url

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

Type:: Type

app_name

CharField

App name

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

Type:: Type

app_placeholder

CharField

App placeholder

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

Type:: Type

app_welcome_message

CharField

App welcome message

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

Type:: Type

property base_api_domain: str

The base API domain for the LLMClient.

This is the domain that is used in the default hostname for the LLMClient.

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: str

The base default hostname for the LLMClient.

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 LLMClient 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 LLMClient 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’

clone(new_name=None, new_version=None, user_profile=None)[source]

Clone the LLMClient instance, creating a new instance with the same configuration.

Parameters:: new_name (Optional[str]) – Optional new name for the cloned LLMClient. If not provided, the name will be suffixed with “-copy”.
Returns:: The cloned LLMClient instance.
Return type:: LLMClient

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

OneToOneField to LLMClientCustomDomain

Custom domain (related name: llmclient)

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

Type:: Type

custom_domain_id: Internal field, use custom_domain instead.

property custom_host: str | None

The custom hostname for the LLMClient.

Examples:

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

example ‘example.example.com’

Returns:: custom hostname
Return type:: Optional[str]

property custom_url: str | None

The custom URL for the LLMClient.

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

Returns:: custom URL
Return type:: Optional[str]

property default_host: str

The default hostname for the LLMClient.

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 LLMClient’s language model responses. Example: 1024

Type:: Type

default_model

CharField

Default model

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

Type:: Type

default_system_role

TextField

Default system role

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

Type:: Type

property default_system_role_enhanced: str

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 LLMClient’s language model. Example: 0.7

Type:: Type

property default_url: str

The default URL for the LLMClient.

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

Returns:: default URL
Return type:: str

deployed

BooleanField

Deployed

Indicates whether the LLMClient 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(*args, invalidate=False, pk=None, name=None, user=None, user_profile=None, account=None, **kwargs)[source]

Retrieve a model instance using caching to optimize performance.

Example usage:

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

# Retrieve a LLMClient instance by name and user profile with caching
llm_client = LLMClient.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:

LLMClient

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

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

Example usage:

# Retrieve LLMClient instances for a user profile with caching
llm_clients = LLMClient.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 LLMClient instances.

Returns:

A queryset of LLMClient instances associated with the user profile.

Return type:

QuerySet

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: str

The hostname for the LLMClient 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

property is_authentication_required: bool[source]

Determines if authentication is required to access the LLMClient.

Returns:: True if authentication is required, otherwise False.
Return type:: bool

llmclientapikey_set

Reverse ForeignKey from LLMClientAPIKey

All LLMClient API Keys of this llm client (related name of llm_client)

Type:: Type

llmclientfunctions_set

Reverse ForeignKey from LLMClientFunctions

All LLMClient Functions of this llm client (related name of llm_client)

Type:: Type

llmclientplugin_set

Reverse ForeignKey from LLMClientPlugin

All LLMClient Plugins of this llm client (related name of llm_client)

Type:: Type

llmclientrequests_set

Reverse ForeignKey from LLMClientRequests

All LLMClient Requests History of this llm client (related name of llm_client)

Type:: Type

property manifest_url: str

The URL for the LLMClient’s manifest file. This is used for integration with external platforms that require a manifest URL.

example: ‘https://alpha.platform.smarter.sh/workbench/llm-clients/<str:hashed_id>/manifest/’

Returns:: manifest URL
Return type:: str

mode(url)[source]

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

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

name

CharField

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

Type:: Type

prompt_set

Reverse ForeignKey from Prompt

All Chats of this llm client (related name of llm_client)

Type:: Type

provider

CharField

Provider

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

Type:: Type

property ready: bool

The readiness status of the LLMClient.

A LLMClient 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 LLMClient.

This name is used in the hostname of the LLMClient’s default and custom URLs. The name is constructed by combining the LLMClient’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 LLMClient name and username
no more than one dot

Examples:

For a LLMClient with name “example” and associated user profile “adminuser”,
that IS the account admin, the resulting RFC 1034 compliant name would be “example”
For a LLMClient 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: str

The sandbox hostname for the LLMClient.

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

example ‘alpha.platform.smarter.sh’

Returns:: sandbox hostname
Return type:: str

property sandbox_url: str

The sandbox URL for the LLMClient.

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

example: ‘https://alpha.platform.smarter.sh/workbench/llm-clients/<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

OneToOneField to LLMClientCustomDomainDNS

Subdomain (related name: llmclient)

The subdomain DNS record associated with this LLMClient. Example: LLMClientCustomDomainDNS(id=1, domain=”my-llm_client.example.com”)

Type:: Type

subdomain_id: Internal field, use subdomain instead.

tagged_items

Reverse GenericRelation from LLMClient

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: str

The URL for the LLMClient depending on its deployment status.

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

Returns:: URL
Return type:: str

property url_chat_config: str

The Smarter Api url for the Prompt config json dict.

The React.js app requests this url during react app startup to retrieve the UI configuration for the llm_client.

maps to “<int:llm_client_id>/config/” example: “http://localhost:9357/api/v1/llm-clients/5174/config/”

Returns:: URL for llm_client 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 “prompt/”

property url_llm_client: str

The Smarter Api url returned by PromptConfigView.config() as the.

key, “url_llm_client”. This url is consumed by React.js app for http requests on new prompts.

maps to “<int:llm_client_id>/prompt/” example: “http://localhost:9357/api/v1/llm-clients/5174/prompt/”

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

user_profile

ForeignKey to UserProfile

User profile (related name: llmclient)

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