Brokers

Smarter API LLMClient Manifest handler.

class smarter.apps.llm_client.manifest.brokers.llm_client.LLMClientSerializer(*args, **kwargs)

Bases: ModelSerializer

Django ORM model serializer for get().

class smarter.apps.llm_client.manifest.brokers.llm_client.SAMLLMClientBroker(*args, **kwargs)

Bases: AbstractBroker

Broker for SAM LLMClient manifests.

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

The broker is responsible for:

• Managing the lifecycle of llm_client 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 llm_client 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 LLMClient, LLMClientAPIKey, LLMClientPlugin, and LLMClientFunctions, to ensure all components of an llm_client 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 llm_clients in the Smarter Framework.

property ORMMetaModelClass: Type[LLMClient]

Return the Django ORM meta model class for the broker.

Returns:

The Django ORM meta model class definition for the broker.

Return type:

Type[LLMClient]

property ORMModelClass: Type[LLMClient]

The Django ORM model class for the LLMClient.

Returns:

The LLMClient Django ORM model class.

Return type:

Type[LLMClient]

property SerializerClass: Type[LLMClientSerializer]

The Django ORM model serializer class for the LLMClient.

Returns:

The LLMClient Django ORM model serializer class.

Return type:

Type[ModelSerializer]

__init__(*args, **kwargs)

Initialize the SAMLLMClientBroker 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 = SAMLLMClientBroker(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.

LLMClient is a composite model that includes the LLMClient, LLMClientAPIKey, LLMClientPlugin and LLMClientFunctions 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 LLMClient when any mutation occurs. In this case, we need to invalidate the LLMClient cache itself, but also any related objects such as the plugins, functions and api keys.

Return type:

None

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 LLMClient model instance into a dictionary compatible with the Smarter API LLMClient manifest format.

This method converts the current LLMClient 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 llm_client. This enables seamless round-trip conversion between database state and manifest representation.

If the LLMClient 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 LLMClient manifest, or None if the LLMClient model is not set.

Return type:

Optional[dict]

Raises:

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

See also:

• smarter.apps.llm_client.manifest.brokers.llm_client.SAMLLMClientBroker.manifest_to_django_orm()

• smarter.apps.llm_client.manifest.models.llm_client.SAMLLMClient

• smarter.apps.llm_client.manifest.models.llm_client.metadata.SAMLLMClientMetadata

• smarter.apps.llm_client.manifest.models.llm_client.spec.SAMLLMClientSpec

• smarter.apps.llm_client.manifest.models.llm_client.status.SAMLLMClientStatus

example_manifest(request, *args, **kwargs)

Return an example manifest for the Smarter API LLMClient.

Returns:

A JSON response containing an example Smarter API LLMClient manifest.

Return type:

SmarterJournaledJsonResponse

See also:

• smarter.apps.llm_client.manifest.models.llm_client.SAMLLMClient

• smarter.lib.manifest.enumSAMKeys

• smarter.apps.llm_client.manifest.enum.SAMMetadataKeys

• smarter.apps.llm_client.manifest.enum.SCLIResponseGet

• smarter.apps.llm_client.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 LLMClient functions.

This property retrieves a list of the names of the LLMClientFunctions Django ORM model objects that are linked to the LLMClient managed by this broker. The functions define the capabilities and operations that the LLMClient 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 LLMClient instance. If no functions are found, None is returned.

Returns:

A list of names of LLMClientFunctions instances associated with the LLMClient, 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 LLMClient.

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

Returns:

The manifest kind string for the Smarter API LLMClient.

Return type:

str

Important

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

property llm_client: LLMClient | None

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

This property retrieves the LLMClient object associated with the broker’s account and name. If a matching LLMClient 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 LLMClient 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 LLMClient model, either by fetching an existing record or by creating one from the manifest specification. The LLMClient model stores the configuration and runtime state of the llm_client, and is used for all database operations related to the llm_client’s lifecycle.

Returns:

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

Return type:

Optional[LLMClient]

Note

The returned LLMClient object is essential for linking related resources such as API keys, plugins, and functions, and for performing updates or queries on the llm_client’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 llm_client_api_key: LLMClientAPIKey | None

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

This property retrieves the LLMClientAPIKey Django ORM model object that is linked to the LLMClient managed by this broker. The API key is used for authenticating requests made by the LLMClient 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 LLMClient 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 LLMClient, such as invoking external APIs or managing secure resources.

Returns:

The LLMClientAPIKey instance associated with the LLMClient, or None if no API key exists.

Return type:

Optional[LLMClientAPIKey]

Important

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

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: SAMLLMClient | None

Returns the Smarter API LLMClient manifest as a Pydantic model.

This method constructs and returns an instance of the SAMLLMClient Pydantic model, which represents the full manifest for a Smarter API LLMClient. The manifest contains all configuration, metadata, and specification details required to describe and deploy an llm_client 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 SAMLLMClient model. The metadata and spec fields are themselves Pydantic models (SAMLLMClientMetadata and SAMLLMClientSpec), 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 SAMLLMClient 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 SAMLLMClient representing the llm_client manifest, or None if the manifest cannot be initialized.

Return type:

Optional[SAMLLMClient]

manifest_to_django_orm()

Convert the Smarter API LLMClient manifest into a dictionary suitable for creating or updating a Django ORM LLMClient 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 LLMClient 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 LLMClient model.

Return type:

dict

Raises:

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

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

property plugins: List[str] | None

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

This property retrieves a list of the names of the LLMClientPlugin Django ORM model objects that are linked to the LLMClient managed by this broker. The plugins extend the functionality of the LLMClient, 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 LLMClient instance. If no plugins are found, None is returned.

Returns:

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

Return type:

Optional[List[str]]

prompt(request, *args, **kwargs)

Invoke a prompt operation.

This abstract method should be implemented by subclasses to provide prompt-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 prompt response.

Return type:

SmarterJournaledJsonResponse

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.llm_client.manifest.brokers.llm_client.SAMLLMClientBrokerError(message=None, thing=None, command=None, stack_trace=None)

Bases: SAMBrokerError

Base exception for Smarter API LLMClient Broker handling.

property get_formatted_err_message