LLMClientHelper Model

class smarter.apps.llmclient.models.LLMClientHelper(request, *args, **kwargs)[source]

Bases: SmarterRequestMixin

Provides a mapping between URLs and their corresponding LLMClient 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 LLMClient 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 LLMClient 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/llm-client/

    • 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/llm-clients/1/

    • https://alpha.api.example-username.com/llm-clients/example/

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

Features

  • Abstracts and encapsulates URL parsing and LLMClient resolution logic.

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

  • Caches LLMClient 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 LLMClient instance and related metadata, such as the associated account, llmclient ID, and custom domain.

Example:

helper = LLMClientHelper(request)
llmclient = helper.llmclient
if helper.is_valid:
    # Proceed with llmclient logic
Parameters:

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

  • args – Additional positional arguments.

  • kwargs – Additional keyword arguments, such as ‘llmclient’, ‘llmclient_custom_domain’, etc.

Raises:

SmarterConfigurationError – If the helper cannot resolve a valid LLMClient 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 LLMClientHelper instance.

Parameters:

  • request (HttpRequest) – The Django HttpRequest object.

  • args – Additional positional arguments.

  • kwargs – Additional keyword arguments.

property account: Account | None[source]

Return the associated Account for this LLMClientHelper 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 LLMClient API URL.

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

Examples

Named URL:

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

Sandbox URL:

  • http://api.localhost:9357/api/v1/llm-clients/1/prompt/ returns 'api.localhost:9357'

Custom domain URL:

  • https://hr.smarter.sh/llm-client/ returns 'hr.smarter.sh'

Returns:

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

Return type:

Optional[str]

property formatted_class_name: str[source]

Get the formatted class name for this instance of LLMClientHelper.

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 LLMClientHelper 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 = LLMClientHelper(request)
>>> helper.formatted_class_name
'smarter.apps.llmclient.models.LLMClientHelper()'
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

property is_custom_domain: bool

Returns True if the LLMClient is using a custom domain.

Returns:

True if a custom domain is configured, otherwise False.

Return type:

bool

property is_deployed: bool
property is_helper_ready: bool[source]

Returns True if the LLMClientHelper is ready to be used.

This is a convenience property that checks if the LLMClientHelper is initialized and has a valid LLMClient instance.

Returns:

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

Return type:

bool

property llmclient: LLMClient | None

Returns a lazy instance of the LLMClient.

Examples

Returns:

The LLMClient instance, or None if not found.

Return type:

Optional[LLMClient]

property llmclient_custom_domain: LLMClientCustomDomain | None

Returns a lazy instance of the LLMClientCustomDomain.

Examples

  • https://hr.smarter.sh/llm-client/ returns LLMClientCustomDomain(domain_name='smarter.sh')

Returns:

The LLMClientCustomDomain instance, or None if not found.

Return type:

Optional[LLMClientCustomDomain]

property llmclient_id: int | None

Returns the LLMClient.id for this LLMClientHelper instance.

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

  1. If an llmclient ID was provided at initialization, it is returned immediately.

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

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

  4. If both an llmclient name and account are available, attempts to resolve and cache the LLMClient object and its ID.

Returns:

The resolved LLMClient ID, or None if not found.

Return type:

Optional[int]

property llmclient_name: str | None

Returns the LLMClient.name for the LLMClientHelper.

property llmclient_plugins_list: list[LLMClientPlugin]

Returns a list of LLMClientPlugin instances associated with the LLMClient.

Returns:

A list of LLMClientPlugin instances.

Return type:

list[LLMClientPlugin]

property llmclient_plugins_list_str: str[source]

Returns a comma-separated string of LLMClientPlugin names associated with the LLMClient.

Returns:

A comma-separated string of LLMClientPlugin names.

Return type:

str

property llmclienthelper_ready_state: str

Returns a formatted string indicating whether the LLMClientHelper is ready.

Returns:

A string indicating whether the LLMClientHelper is ready or not.

property name: str | None

Returns the name of the llmclient.

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

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

  2. self.llmclient.name: The name attribute of the resolved LLMClient instance, if present.

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

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

Returns:

The resolved llmclient name, or None if not found.

Return type:

Optional[str]

property provider: Provider | None[source]

Returns the Provider associated with the LLMClient.

Returns:

The Provider instance, or None if not found.

Return type:

Optional[Provider]

property ready: bool

Returns True if the LLMClientHelper and its LLMClient are ready to be used.

This property checks both the readiness of the LLMClientHelper itself and the readiness of the underlying LLMClient instance.

Returns:

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

Return type:

bool

property rfc1034_compliant_name: str | None

Returns a URL-friendly name for the llmclient.

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

Examples

self.name  # 'Example LLMClient 1'
self.rfc1034_compliant_name  # 'example-llmclient-1'
Returns:

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

Return type:

Optional[str]

to_json()[source]

Serialize the LLMClientHelper to a dictionary.

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

Returns:

A dictionary containing the serialized state of the LLMClientHelper.

Return type:

dict[str, Any]