Brokers

Smarter API Chatbot Manifest handler

class smarter.apps.chatbot.manifest.brokers.chatbot.ChatBotSerializer(*args, **kwargs)

Bases: ModelSerializer

Django ORM model serializer for get()

class smarter.apps.chatbot.manifest.brokers.chatbot.SAMChatbotBroker(*args, **kwargs)

Bases: AbstractBroker

Broker for SAM Chatbot manifests.

This class provides a high-level abstraction for managing chatbot manifests within the Smarter platform. It acts as the central coordinator for the lifecycle of chatbot manifests, bridging the gap between declarative YAML files and persistent application state.

The broker is responsible for:

• Managing the lifecycle of chatbot manifests, including loading, validation, and parsing of YAML files.

• Initializing Pydantic models from manifest data to ensure robust schema validation and serialization.

• Integrating with Django ORM models that represent chatbot manifests, supporting creation, update, deletion, and querying of database records.

• Transforming data between Django ORM models and Pydantic models to enable seamless conversion between database and API representations.

• Coordinating composite models, such as ChatBot, ChatBotAPIKey, ChatBotPlugin, and ChatBotFunctions, to ensure all components of a chatbot are synchronized according to the manifest specification.

• Ensuring atomic and consistent application of changes using Django’s transaction management.

• Providing detailed logging and error handling integrated with the Smarter platform’s diagnostics systems.

This broker is a key component in the deployment, configuration, and lifecycle management of chatbots in the Smarter Framework.

property ORMMetaModelClass: Type[ChatBot]

Return the Django ORM meta model class for the broker.

Returns:

The Django ORM meta model class definition for the broker.

Return type:

Type[ChatBot]

property ORMModelClass: Type[ChatBot]

The Django ORM model class for the ChatBot.

Returns:

The ChatBot Django ORM model class.

Return type:

Type[ChatBot]

property SerializerClass: Type[ChatBotSerializer]

The Django ORM model serializer class for the ChatBot.

Returns:

The ChatBot Django ORM model serializer class.

Return type:

Type[ModelSerializer]

__init__(*args, **kwargs)

Initialize the SAMChatbotBroker instance.

This constructor initializes the broker by calling the parent class’s constructor, which will attempt to bootstrap the class instance with any combination of raw manifest data (in JSON or YAML format), a manifest loader, or existing Django ORM models. If a manifest loader is provided and its kind matches the expected kind for this broker, the manifest is initialized using the loader’s data.

This class can bootstrap itself in any of the following ways:

• request.body (yaml or json string)

• name + account (determined via authentication of the request object)

• SAMLoader instance

• manifest instance

• filepath to a manifest file

If raw manifest data is provided, whether as a string or a dictionary, or a SAMLoader instance, the base class constructor will only goes as far as initializing the loader. The actual manifest model initialization is deferred to this constructor, which checks the loader’s kind.

Parameters:

• args – Positional arguments passed to the parent constructor.

• kwargs – Keyword arguments passed to the parent constructor.

Example:

broker = SAMChatbotBroker(loader=loader, plugin_meta=plugin_meta)

See also

• SAMPluginBaseBroker.__init__

apply(request, *args, **kwargs)

apply the manifest. copy the manifest data to the Django ORM model and save the model to the database. Call super().apply() to ensure that the manifest is loaded and validated before applying the manifest to the Django ORM model. Note that there are fields included in the manifest that are not editable and are therefore removed from the Django ORM model dict prior to attempting the save() command. These fields are defined in the readonly_fields list.

Chatbot is a composite model that includes the ChatBot, ChatBotAPIKey, ChatBotPlugin and ChatBotFunctions models. All of these are represented in the manifest spec and are created or updated as needed.

Note

tags are handled separately because they are of type TaggableManager and require a different method to set them.

Return type:

SmarterJournaledJsonResponse

cache_invalidations()

Handle broker specific cache invalidation logic. We should invalidate any cached objects that are related to the ChatBot when any mutation occurs. In this case, we need to invalidate the ChatBot cache itself, but also any related objects such as the plugins, functions and api keys.

Return type:

None

chat(request, *args, **kwargs)

Invoke a chat operation.

This abstract method should be implemented by subclasses to provide chat-based interactions with the broker resource.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the chat response.

Return type:

SmarterJournaledJsonResponse

property chatbot: ChatBot | None

Provides access to the Django ORM model instance representing the current Smarter ChatBot.

This property retrieves the ChatBot object associated with the broker’s account and name. If a matching ChatBot record exists in the database, it is returned and cached for future access. If no such record exists, and a manifest is available, a new ChatBot instance is created using data extracted from the manifest and then persisted to the database.

This property ensures that the broker always has access to a valid ChatBot model, either by fetching an existing record or by creating one from the manifest specification. The ChatBot model stores the configuration and runtime state of the chatbot, and is used for all database operations related to the chatbot’s lifecycle.

Returns:

The Django ORM ChatBot instance if found or created, otherwise None if neither a database record nor a manifest is available.

Return type:

Optional[ChatBot]

Note

The returned ChatBot object is essential for linking related resources such as API keys, plugins, and functions, and for performing updates or queries on the chatbot’s state.

FIX NOTE

This should be refactored/removed in favor of orm_instance. There is no logic in this property that merits it overriding the parent orm_instance property.

FIX NOTE

This is breaking an unwritten rule of Smarter resources in that it is lazily creating a database record on a property getter. Creating/updating database records should be handled in apply().

property chatbot_api_key: ChatBotAPIKey | None

Provides access to the API key associated with the current ChatBot instance.

This property retrieves the ChatBotAPIKey Django ORM model object that is linked to the ChatBot managed by this broker. The API key is used for authenticating requests made by the ChatBot and is stored securely in the database.

If the API key has already been retrieved and cached, it is returned immediately. Otherwise, the property attempts to fetch the API key from the database using the current ChatBot instance. If no API key is found, None is returned.

This property is essential for operations that require authentication or authorization on behalf of the ChatBot, such as invoking external APIs or managing secure resources.

Returns:

The ChatBotAPIKey instance associated with the ChatBot, or None if no API key exists.

Return type:

Optional[ChatBotAPIKey]

Important

If the ChatBotAPIKey is None, it indicates that no API key has been set for the ChatBot, which in turn will enable anonymous unauthenticated access for the ChatBot.

delete(request, *args, **kwargs)

delete a resource.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the result of the delete operation.

Return type:

SmarterJournaledJsonResponse

deploy(request, *args, **kwargs)

deploy a resource.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the result of the deploy operation.

Return type:

SmarterJournaledJsonResponse

describe(request, *args, **kwargs)

describe a resource.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the description of the resource.

Return type:

SmarterJournaledJsonResponse

django_orm_to_manifest_dict()

Transform the Django ORM ChatBot model instance into a dictionary compatible with the Smarter API Chatbot manifest format.

This method converts the current ChatBot ORM model and its related resources (plugins, functions, API key) into a dictionary structure that matches the expected schema for a Pydantic manifest. The conversion includes renaming fields from snake_case to camelCase, removing internal-only fields, and assembling metadata, spec, and status sections as required by the manifest.

The resulting dictionary contains all configuration, metadata, plugin, function, and status information necessary to reconstruct the manifest for the chatbot. This enables seamless round-trip conversion between database state and manifest representation.

If the ChatBot model is not available, the method logs a warning and returns None. If the conversion fails, an exception is raised to indicate the error.

Returns:

A dictionary representing the Smarter API Chatbot manifest, or None if the ChatBot model is not set.

Return type:

Optional[dict]

Raises:

SAMChatbotBrokerError – If the ORM model cannot be converted to a manifest dictionary.

See also:

• smarter.apps.chatbot.manifest.brokers.chatbot.SAMChatbotBroker.manifest_to_django_orm()

• smarter.apps.chatbot.manifest.models.chatbot.SAMChatbot

• smarter.apps.chatbot.manifest.models.chatbot.metadata.SAMChatbotMetadata

• smarter.apps.chatbot.manifest.models.chatbot.spec.SAMChatbotSpec

• smarter.apps.chatbot.manifest.models.chatbot.status.SAMChatbotStatus

example_manifest(request, *args, **kwargs)

Return an example manifest for the Smarter API Chatbot.

Returns:

A JSON response containing an example Smarter API Chatbot manifest.

Return type:

SmarterJournaledJsonResponse

See also:

• smarter.apps.chatbot.manifest.models.chatbot.SAMChatbot

• smarter.lib.manifest.enumSAMKeys

• smarter.apps.chatbot.manifest.enum.SAMMetadataKeys

• smarter.apps.chatbot.manifest.enum.SCLIResponseGet

• smarter.apps.chatbot.manifest.enum.SCLIResponseGetData

• from smarter.common.conf.settings_defaults

property formatted_class_name: str

Returns a formatted string representing the class name for logging purposes.

This property generates a human-readable class name that is used to improve the clarity and consistency of log messages throughout the broker. The formatted class name includes the parent class name and appends the specific broker class identifier, making it easier to trace log entries back to their source within the codebase.

The formatted class name is especially useful in environments where multiple brokers or components are active, as it helps distinguish log messages and aids in debugging and monitoring application behavior.

Returns:

A string containing the formatted class name, suitable for use in log output.

Return type:

str

property functions: List[str] | None

Provides access to the Django ORM model class representing ChatBot functions.

This property retrieves a list of the names of the ChatBotFunctions Django ORM model objects that are linked to the ChatBot managed by this broker. The functions define the capabilities and operations that the ChatBot can perform, as specified in the manifest.

If the functions have already been retrieved and cached, they are returned immediately. Otherwise, the property attempts to fetch the functions from the database using the current ChatBot instance. If no functions are found, None is returned.

Returns:

A list of names of ChatBotFunctions instances associated with the ChatBot, or None if no functions exist.

Return type:

Optional[List[str]]

get(request, *args, **kwargs)

get information about specified resources.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the result of the get operation.

Return type:

SmarterJournaledJsonResponse

property kind: str

Returns the manifest kind for the Smarter API Chatbot.

This property provides the specific kind identifier used to classify the Smarter API Chatbot manifest within the Smarter platform. The kind is a key component of the manifest schema, allowing the system to recognize and process chatbot manifests appropriately. The kind value is defined as a constant in the chatbot manifest model and is used throughout the broker to ensure consistency when handling chatbot manifests.

Returns:

The manifest kind string for the Smarter API Chatbot.

Return type:

str

Important

The kind property is essential for manifest validation, routing, and processing within the Smarter platform.

logs(request, *args, **kwargs)

get logs for a resource.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the logs for the resource.

Return type:

SmarterJournaledJsonResponse

property manifest: SAMChatbot | None

Returns the Smarter API Chatbot manifest as a Pydantic model.

This method constructs and returns an instance of the SAMChatbot Pydantic model, which represents the full manifest for a Smarter API Chatbot. The manifest contains all configuration, metadata, and specification details required to describe and deploy a chatbot within the Smarter platform.

The manifest is initialized using data provided by the manifest loader. The loader supplies the manifest’s API version, kind, metadata, and specification, which are passed to the respective fields of the SAMChatbot model. The metadata and spec fields are themselves Pydantic models (SAMChatbotMetadata and SAMChatbotSpec), and are recursively initialized with their corresponding data.

Unlike child models, which are automatically cascade-initialized by Pydantic when constructing the parent model, the top-level manifest model must be explicitly instantiated in this method. This ensures that all manifest data is validated and structured according to the schema defined by the SAMChatbot model.

If the manifest has already been initialized and cached, this method returns the cached instance. If the loader is present and its manifest kind matches the expected kind, a new manifest instance is created and cached before returning.

Returns:

An instance of SAMChatbot representing the chatbot manifest, or None if the manifest cannot be initialized.

Return type:

Optional[SAMChatbot]

manifest_to_django_orm()

Convert the Smarter API Chatbot manifest into a dictionary suitable for creating or updating a Django ORM ChatBot model.

This method extracts all relevant configuration, metadata, and versioning information from the loaded manifest and transforms it into a dictionary format compatible with Django ORM operations. The manifest’s configuration is first dumped and converted from camelCase to snake_case to match Django’s field naming conventions.

The resulting dictionary includes the account, name, description, and version fields from the manifest metadata, as well as all configuration fields from the manifest specification. This dictionary can be used to instantiate or update a ChatBot ORM model instance in the database.

If the manifest is not loaded or is invalid, an exception is raised to indicate that the broker is not ready to perform the transformation.

Returns:

A dictionary containing all fields required to create or update a Django ORM ChatBot model.

Return type:

dict

Raises:

• SAMBrokerErrorNotReady – If the manifest is not loaded or cannot be found.

• SAMChatbotBrokerError – If the manifest configuration cannot be converted to a dictionary.

property plugins: List[str] | None

Provides access to the Django ORM model class representing ChatBot plugins.

This property retrieves a list of the names of the ChatBotPlugin Django ORM model objects that are linked to the ChatBot managed by this broker. The plugins extend the functionality of the ChatBot, as specified in the manifest.

If the plugins have already been retrieved and cached, they are returned immediately. Otherwise, the property attempts to fetch the plugins from the database using the current ChatBot instance. If no plugins are found, None is returned.

Returns:

A list of names of ChatBotPlugin instances associated with the ChatBot, or None if no plugins exist.

Return type:

Optional[List[str]]

property ready: bool

Check if the broker is ready for operations.

This property determines whether the broker has been properly initialized and is ready to perform its functions. A broker is considered ready if it has a valid manifest loaded, either from raw data, a loader, or existing Django ORM models.

Returns:

True if the broker is ready, False otherwise.

Return type:

bool

undeploy(request, *args, **kwargs)

undeploy a resource.

Parameters:

• request (HttpRequest) – The HTTP request object.

• args – Additional positional arguments.

• kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the result of the undeploy operation.

Return type:

SmarterJournaledJsonResponse

exception smarter.apps.chatbot.manifest.brokers.chatbot.SAMChatbotBrokerError(message=None, thing=None, command=None, stack_trace=None)

Bases: SAMBrokerError

Base exception for Smarter API Chatbot Broker handling.

property get_formatted_err_message

smarter.apps.chatbot.manifest.brokers.chatbot.should_log(level)

Check if logging should be done based on the waffle switch.