Smarter Broker Model

Smarter API Manifest Abstract Broker class.

class smarter.lib.manifest.broker.abstract_broker_class.AbstractBroker(request, *args, name=None, kind=None, loader=None, api_version='smarter.sh/v1', manifest=None, file_path=None, url=None, **kwargs)[source]

Bases: ABC, SmarterRequestMixin

Abstract base class for the Smarter Broker Model.

This class defines the core broker service pattern for the Smarter API, and is the foundation for all concrete Broker implementations. Brokers are responsible for processing Smarter YAML manifests, initializing Pydantic models, and brokering the correct implementation class for CLI and API operations.

Responsibilities

Load, partially validate, and parse a Smarter API YAML manifest, sufficient to initialize a Pydantic model.
Implement the broker service pattern for the underlying object.
Initialize the corresponding Pydantic models.
Instantiate the underlying Python object for the resource.

The broker pattern provides generic services for manifest operations, including: get, post, put, delete, and patch.

Subclasses must implement the abstract methods to provide resource-specific logic for CLI and API commands such as apply, describe, delete, deploy, example_manifest, get, logs, and undeploy.

abstract property ORMMetaModelClass: Type[MetaDataWithOwnershipModel]

Return the Django ORM meta model class for the broker.

Returns:: The Django ORM meta model class definition for the broker.
Return type:: Type[MetaDataWithOwnershipModel]

abstract property ORMModelClass: Type[MetaDataWithOwnershipModel]

Return the Django ORM model class for the broker.

Returns:: The Django ORM model class definition for the broker.
Return type:: Type[MetaDataWithOwnershipModel]

property SAMModelClass: Type[AbstractSAMBase]

Return the SAM (Smarter Api Manifest) model class for the broker.

Returns:: The Pydantic model class definition for the broker.
Return type:: Type[AbstractSAMBase]

abstract property SerializerClass: Type[ModelSerializer]

Return the serializer class for the broker.

Returns:: The serializer class definition for the broker.
Return type:: Type[ModelSerializer]

__init__(request, *args, name=None, kind=None, loader=None, api_version='smarter.sh/v1', manifest=None, file_path=None, url=None, **kwargs)[source]

property abstract_broker_logger_cache_invalidation_prefix: str

Return the logger prefix for the AbstractBroker cache invalidation.

Returns:: The logger prefix for the AbstractBroker.
Return type:: str

property abstract_broker_logger_prefix: str

Return the logger prefix for the AbstractBroker.

Returns:: The logger prefix for the AbstractBroker.
Return type:: str

property abstract_broker_ready_state: str

Return a string representation of the AbstractBroker’s ready state.

Returns:: “READY” if the AbstractBroker is ready, otherwise “NOT_READY”.
Return type:: str

property api_version: str

The API version of the manifest.

Returns:: The API version of the manifest.
Return type:: Optional[str]

apply(request, *args, **kwargs)[source]

Apply a manifest, which works like an upsert operation.

Designed around the Kubernetes kubectl apply command.

This method processes a Smarter YAML manifest and either creates or updates the corresponding resource, depending on whether it already exists.

Example manifest metadata:

metadata:
    description: new description
    name: test71d12b8212b628df
    version: 1.0.0

Parameters:

request (HttpRequest) – The HTTP request object.
args – Additional positional arguments.
kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse if implemented, otherwise None.

Return type:

Optional[SmarterJournaledJsonResponse]

Todo

Research why this is not an abstract method.

cache_invalidations()[source]

Handle broker specific cache invalidation logic.

Return type:: None

clean_cli_param(param, param_name='unknown', url=None)[source]

Remove any leading or trailing whitespace from the param.
Ensure that the param is a string.
Return the cleaned param.

Parameters:

param (Any) – The param to clean.
param_name (str) – The name of the param, for logging purposes.
url (Optional[str]) – The url from which the param was extracted, for logging purposes.

Returns:

The cleaned param.

Return type:

Optional[str]

property created: bool

Return True if the broker was created successfully.

Returns:: True if the broker was created successfully.
Return type:: bool

abstractmethod delete(request, *args, **kwargs)[source]

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

abstractmethod deploy(request, *args, **kwargs)[source]

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

abstractmethod describe(request, *args, **kwargs)[source]

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

abstractmethod example_manifest(request, *args, **kwargs)[source]

Returns an example yaml manifest document for the kind of resource.

Parameters:

request (HttpRequest) – The HTTP request object.
args – Additional positional arguments.
kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the example manifest.

Return type:

SmarterJournaledJsonResponse

property formatted_class_name: str

Return the logger prefix for the AbstractBroker.

Returns:: The logger prefix for the AbstractBroker.
Return type:: str

property formatted_class_name_cache_invalidations: str

Return the logger prefix for the AbstractBroker cache invalidations.

Returns:: The logger prefix for the AbstractBroker cache invalidations.
Return type:: str

abstractmethod get(request, *args, **kwargs)[source]

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

get_model_titles(serializer)[source]

For tabular output from get() implementations.

Returns a list of field names and types from the Django model serializer.

Parameters:: serializer (ModelSerializer) – The Django model serializer instance.
Returns:: A list of field names and types.
Return type:: Optional[list[dict[str, str]]]

get_or_create_secret(user_profile, name, value=None, description=None, expiration=None)[source]

Get or create a Smarter Secret in the database.

This is used to store secrets that are passed in the manifest.

Parameters:

user_profile (UserProfile) – The UserProfile to associate the secret with.
name (str) – The name of the secret.
value (Optional[str]) – The value of the secret.
description (Optional[str]) – A description of the secret.
expiration (Optional[datetime]) – The expiration date of the secret.

Returns:

The created or retrieved Secret object.

Return type:

Secret

property is_ready_abstract_broker: bool

Return True if the AbstractBroker is ready for operations.

An AbstractBroker is considered ready if: - The AccountMixin is ready. - The RequestMixin is ready. - either a valid manifest is loaded or a ready SAMLoader is present.

Returns:: True if the AbstractBroker is ready for operations.
Return type:: bool

property is_valid: bool

json_response_err(command, e)[source]

Return a structured error response that can be unpacked and rendered.

by the cli in a variety of formats.

Parameters:

command (SmarterJournalCliCommands) – The command that was executed.
e (Exception) – The exception that was raised.

Returns:

A SmarterJournaledJsonResponse containing the error response.

Return type:

SmarterJournaledJsonResponse

json_response_err_notfound(command, message=None)[source]

Return a common not found response.

Parameters:

command (SmarterJournalCliCommands) – The command that was executed.
message (Optional[str]) – An optional custom message to include in the response.

Returns:

A SmarterJournaledJsonResponse containing the not found response.

Return type:

SmarterJournaledJsonResponse

json_response_err_notimplemented(command)[source]

Return a common not implemented response.

Parameters:: command (SmarterJournalCliCommands) – The command that was executed.
Returns:: A SmarterJournaledJsonResponse containing the not implemented response.
Return type:: SmarterJournaledJsonResponse

json_response_err_notready(command)[source]

Return a common not ready response.

Parameters:: command (SmarterJournalCliCommands) – The command that was executed.
Returns:: A SmarterJournaledJsonResponse containing the not ready response.
Return type:: SmarterJournaledJsonResponse

json_response_err_readonly(command)[source]

Return a common read-only response.

Parameters:: command (SmarterJournalCliCommands) – The command that was executed.
Returns:: A SmarterJournaledJsonResponse containing the read-only response.
Return type:: SmarterJournaledJsonResponse

json_response_ok(command, data=None, message=None)[source]

Return a common success response.

Parameters:

command (SmarterJournalCliCommands) – The command that was executed.
data (Optional[dict]) – The data to return in the response.
message (Optional[str]) – An optional message to include in the response.

Returns:

A SmarterJournaledJsonResponse containing the success response.

Return type:

SmarterJournaledJsonResponse

property kind: str | None

The kind of manifest.

Returns:: The kind of manifest.
Return type:: Optional[str]

kind_setter(value)[source]

Set the kind of manifest.

Validates that the kind is a valid SmarterJournalThings value.

Raises:: SmarterValueError – If the kind is not valid.
Parameters:: value (str) – The kind of manifest to set.

property loader: SAMLoader | None

The SAMLoader instance for this broker.

Returns:: The SAMLoader instance for this broker.
Return type:: Optional[SAMLoader]

log_abstract_broker_state()[source]

Log the current state of the AbstractBroker instance for debugging purposes.

Returns:: None

abstractmethod logs(request, *args, **kwargs)[source]

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

abstract property manifest: AbstractSAMBase | dict | None

The Pydantic model representing the manifest.

If the manifest has not been initialized yet, this property will attempt to initialize it using the SAMLoader.

Returns:: The Pydantic model representing the manifest.
Return type:: Optional[AbstractSAMBase]

manifest_setter(value)[source]

Set the manifest for the broker and override all AbstractBroker.

model properties based on the manifest data.

Parameters:: value (Union[AbstractSAMBase, dict[str, Any], None]) – The manifest to set, either as a Pydantic model or a dictionary.

manifest_to_django_orm()[source]

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

This method extracts all relevant metadata 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. This dictionary is intended to be used to supplement the model spec when instantiating or updating 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 metadata fields required to create or update a Django ORM LLMClient model.

Return type:

dict[str, Any]

Raises:

SAMBrokerErrorNotReady – If the manifest is not loaded or cannot be found.
SAMLLMClientBrokerError – If the manifest metadata cannot be converted to a dictionary.

property name: str | None

Retrieve the unique name identifier for the LLMClient instance managed by this broker.

This property accesses the name used to distinguish the LLMClient within the database and across the Smarter platform. The name is first returned from an internal cache if available. If not cached, and if a manifest is present, the name is extracted from the manifest’s metadata and stored for subsequent access.

The name is essential for database queries, model lookups, and for associating related resources such as API keys, plugins, and functions with the correct LLMClient instance.

Returns:: The name of the LLMClient as a string, or None if the name is not set or cannot be determined.
Return type:: Optional[str]

Note

The name property is a critical identifier used throughout the broker to ensure correct mapping between manifest data and persistent application state.

name_cached_property_setter(value)[source]

A workaround to the limitation that you cannot use both @cached_property and.

a setter for the same attribute name (name). In Python, you cannot have a property (or cached_property) and a setter with the same name unless you use the @property decorator (not @cached_property).

We need the cached_property so that the lazy evaluation of the name only happens once, and subsequent accesses return the cached value for performance. However, we also need to be able to set the name explicitly in some cases,

Parameters:: value (str) – The name to set for the manifest.

property orm_instance: MetaDataWithOwnershipModel | None

Return the Django ORM model instance for the broker.

There are multiple strategies to retrieve the ORM instance:

If the instance is already cached in self._orm_instance, return it.
If the broker is not ready or the name is not set, log a warning and return None.
Attempt to retrieve the ORM instance using the user_profile and name. If not found, attempt to retrieve using the admin user_profile for the account. If still not found, attempt to retrieve using the Smarter platform admin user_profile.
Cache the retrieved instance for future access.

Returns:: The Django ORM model instance for the broker.
Return type:: Optional[MetaDataWithOwnershipModel]

property orm_meta_instance: MetaDataWithOwnershipModel | None

Return the Django ORM meta model instance for the broker.

This is a cached property that retrieves the ORM meta instance based on the user_profile and kind. For simple relational models, the ORM meta class is the same as the ORM class, and the meta instance is the same as the ORM instance.

This property is used for resolving more complex ORM relationships where the name and user_profile fields are stored in a parent Django model.

orm_meta_instance_setter()[source]

Initialize the ORM metadata for the broker instance.

This method attempts to initialize the ORM metadata by querying the ORMMetaModelClass using the broker’s name and user_profile. If the ORM metadata is successfully retrieved, it is stored in the orm_meta_instance attribute. If the ORM metadata does not exist or an error occurs, the _orm_instance attribute is set to None.

Return type:: None
Returns:: None

property params: QueryDict | None

Return the query parameters from the url of the request.

there are two scenarios to consider: 1. the request is a Django HttpRequest object (the expected case) 2. the request is a Python PreparedRequest object (the edge case)

Returns:: The query parameters from the url of the request.
Return type:: Optional[QueryDict]

abstractmethod prompt(request, *args, **kwargs)[source]

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

Return True if the broker is ready for operations.

A broker is considered ready if it has a valid manifest loaded.

Returns:: True if the broker is ready for operations.
Return type:: bool

property ready_state: str

Return a string representation of the broker’s ready state.

Returns:: “READY” if the broker is ready, otherwise “NOT_READY”.
Return type:: str

property request: HttpRequest | None

Return the request object.

Returns:: The request object.
Return type:: Optional[HttpRequest]

schema(request, *args, **kwargs)[source]

Return the published JSON schema for the Pydantic model.

Parameters:

request (HttpRequest) – The HTTP request object.
args – Additional positional arguments.
kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the JSON schema.

Return type:

SmarterJournaledJsonResponse

set_and_verify_name_param(*args, command=None, **kwargs)[source]

Set self.name from the ‘name’ query string param and then verify that it.

was actually passed.

Parameters:: command (Optional[SmarterJournalCliCommands]) – The command being executed, for error reporting purposes.
Raises:: SAMBrokerErrorNotReady – If neither a manifest nor a name param is provided.
Returns:: None

property thing: SmarterJournalThings

The Smarter Journal Thing for this broker.

Returns:: The Smarter Journal Thing for this broker.
Return type:: SmarterJournalThings, an enumeration of all Smarter AI resource types.

to_json()[source]

Serialize the broker instance to a JSON string.

Returns:: A JSON string representation of the broker instance.
Return type:: dict[str, Any]

abstractmethod undeploy(request, *args, **kwargs)[source]

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

property uri: str | None

Return the full uri of the request.

Returns:: The full uri of the request.
Return type:: Optional[str]

class smarter.lib.manifest.broker.abstract_broker_class.BrokerNotImplemented(request=None, api_version=None, account=None, name=None, kind=None, loader=None, manifest=None, file_path=None, url=None)[source]

Bases: AbstractBroker

An error class to proxy for a broker class that has not been implemented.

property ORMModelClass: Type[Model]

Return the Django ORM model class for the broker.

Returns:: The Django ORM model class definition for the broker.
Return type:: Type[MetaDataWithOwnershipModel]

property SerializerClass: Type[ModelSerializer]

Return the serializer class for the broker.

Returns:: The serializer class definition for the broker.
Return type:: Type[ModelSerializer]

__init__(request=None, api_version=None, account=None, name=None, kind=None, loader=None, manifest=None, file_path=None, url=None)[source]

delete(request, *args, **kwargs)[source]

Delete a resource.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – 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)[source]

Deploy a resource.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – 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)[source]

Describe a resource.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – The HTTP request object.
args – Additional positional arguments.
kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the description of the resource.

Return type:

SmarterJournaledJsonResponse

example_manifest(request, *args, **kwargs)[source]

Returns an example yaml manifest document for the kind of resource.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – The HTTP request object.
args – Additional positional arguments.
kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the example manifest.

Return type:

SmarterJournaledJsonResponse

get(request, *args, **kwargs)[source]

Get information about specified resources.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – 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

logs(request, *args, **kwargs)[source]

Get logs for a resource.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – 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: AbstractSAMBase | dict | None

The Pydantic model representing the manifest.

If the manifest has not been initialized yet, this property will attempt to initialize it using the SAMLoader.

Returns:: The Pydantic model representing the manifest.
Return type:: Optional[AbstractSAMBase]

prompt(request, *args, **kwargs)[source]

Invoke a prompt operation.

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

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – The HTTP request object.
args – Additional positional arguments.
kwargs – Additional keyword arguments.

Returns:

A SmarterJournaledJsonResponse containing the prompt response.

Return type:

SmarterJournaledJsonResponse

undeploy(request, *args, **kwargs)[source]

Undeploy a resource.

Parameters:

request (Union[HttpRequest, Request, ASGIRequest]) – 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

smarter.lib.manifest.broker.abstract_broker_class.should_log(level)[source]: Check if logging should be done based on the waffle switch.