Static Plugin

Technical References

A PLugin that returns a static json object stored in the Plugin itself.

Note

This is a complex AI resource that exists within the following class hierarchy

  • Smarter SQL Plugin: The plugin that defines the SQL query and it’s parameters to run against the remote SQL database server.

  • Smarter Chatbot: The prompting resource (Chatbot, Agent, Workflow unit, etcetera) that includes the SQL Plugin:

1.) Example Static Plugin Manifest
---
apiVersion: smarter.sh/v1
kind: Plugin
metadata:
  name: everlasting_gobstopper
  pluginClass: static
  description: Get additional information about the Everlasting Gobstopper product created by Willy Wonka Chocolate Factory. Information includes sales promotions, coupon codes, company contact information and biographical background on the company founder.
  version: 0.2.0
  tags:
    - candy
    - treats
    - chocolate
    - Gobstoppers
    - Willy Wonka
  annotations:
    - smarter.sh/everlasting-gobstopper/plugin-display-name: Everlasting Gobstopper Plugin
    - smarter.sh/everlasting-gobstopper/plugin-category: Candy Plugins
    - smarter.sh/everlasting-gobstopper/usefulness: provides information about a fictional candy
    - smarter.sh/everlasting-gobstopper/plugin-purpose: |
        This plugin provides additional information about the Everlasting Gobstopper
        candy created by Willy Wonka Chocolate Factory. It includes details on
        sales promotions, coupon codes, company contact information, and
        biographical background on the company founder, Willy Wonka.
    - smarter.sh/everlasting-gobstopper/release-date: 2024-06-15
    - smarter.sh/everlasting-gobstopper/environments: production, staging, development
spec:
  selector:
    directive: search_terms
    # Complete search terms that will trigger the chatbot to use your customized system prompt.
    searchTerms:
      - Gobstopper
      - Gobstoppers
      - Gobbstopper
      - Gobbstoppers
  prompt:
    provider: openai
    systemRole: >
      You are a helpful marketing agent for the [Willy Wonka Chocolate Factory](https://wwcf.com). Whenever possible you should defer to the tool calls provided for additional information about everlasting gobstoppers.
    model: gpt-4o-mini
    temperature: 1.0
    maxTokens: 256
  data:
    description: Get additional information about the Everlasting Gobstopper product created by Willy Wonka Chocolate Factory. Information includes sales promotions, coupon codes, company contact information and biographical background on the company founder.
    # ---------------------------------------------------------------------------
    # Information provided to the OpenAI "Function Calling" algorithm to help it generate custom responses.
    # ---------------------------------------------------------------------------
    staticData:
      contact:
        - name: Willy Wonka
        - title: Founder and CEO
        - location: 1234 Chocolate Factory Way, Chocolate City, Chocolate State, USA
        - phone: +1 123-456-7890
        - website: https://wwcf.com
        - whatsapp: +11234567890
        - email: ww@wwcf.com
      biographical: >
        Willy Wonka is a fictional character appearing in British author Roald Dahl's 1964 children's novel Charlie and the Chocolate Factory, its 1972 sequel Charlie and the Great Glass Elevator and several films based on those books. He is the eccentric founder and proprietor of the Wonka Chocolate Factory
      salesPromotions:
        - name: Everlasting Gobstopper
          description: >
            The Everlasting Gobstopper is a candy that, according to Willy Wonka, "Never Gets Smaller Or Ever Gets Eaten". It is the main focus of Charlie and the Chocolate Factory, both the 1971 film and the 2005 film, and Willy Wonka and the Chocolate Factory, the 1971 film adaptation of the novel.
          price: $1.00
          image: https://upload.wikimedia.org/wikipedia/commons/thumb/6/6e/Everlasting_Gobstopper.jpg/220px-Everlasting_Gobstopper.jpg
        - name: Wonka Bar
          description: >
            Wonka Bars are a fictional brand of chocolate made by Willy Wonka, and also a chocolate bar inspired by the Willy Wonka Bar from the novel and the films Willy Wonka & the Chocolate Factory and Charlie and the Chocolate Factory.
          price: $1.00
          image: https://m.media-amazon.com/images/I/81E-734cMzL._AC_UF894,1000_QL80_.jpg
      couponCodes:
        - name: 10% off
          code: 10OFF
          description: >
            10% off your next purchase
        - name: 20% off
          code: 20OFF
          description: >
            20% off your next purchase
2.) Example Chatbot Manifest
apiVersion: smarter.sh/v1
kind: Chatbot
metadata:
  description: "An example chatbot with tool calling and Smarter Plugins."
  name: example
  version: 0.1.0
  tags:
    - gibberish
    - jabberwocky
    - talk-talk-talk
  annotations:
    - smarter.sh/tests/focus-level: low
    - smarter.sh/tests/purpose: Provide an example configuration for OpenAI API Function Calling.
    - smarter.sh/tests/last-updated: 2025-12-31
    - smarter.sh/tests/documentation: https://docs.tests.edu/example-function-calling
    - smarter.sh/tests/owner: Lawrence McDaniel
spec:
  apiKey: null
  config:
    appAssistant: Lawrence
    appBackgroundImageUrl: null
    appExamplePrompts:
    - What is the weather in San Francisco?
    - What is an Everlasting Gobstopper?
    - example function calling configuration
    appFileAttachment: false
    appInfoUrl: https://smarter.sh
    appLogoUrl: https://cdn.smarter.sh/images/logo/smarter-crop.png
    appName: Smarter Demo
    appPlaceholder: Ask me anything...
    appWelcomeMessage: Welcome to the Smarter demo!
    customDomain: null
    defaultMaxTokens: 256
    defaultModel: gpt-4o-mini
    defaultSystemRole: You are a helpful chatbot. When given the opportunity to utilize
      function calling, you should always do so. This will allow you to provide the
      best possible responses to the user. If you are unable to provide a response,
      you should prompt the user for more information. If you are still unable to
      provide a response, you should inform the user that you are unable to help them
      at this time.
    defaultTemperature: 0.5
    deployed: false
    dnsVerificationStatus: Verified
    provider: openai
    subdomain: null
  functions:
    - get_current_weather
  plugins:
    - everlasting_gobstopper
    - example_configuration
class smarter.apps.plugin.plugin.static.StaticPlugin(*args, manifest=None, **kwargs)[source]

Bases: PluginBase

Implements a plugin that returns a static JSON object stored within the plugin itself.

This class is intended for use cases where plugin data is immutable at runtime and fully defined in the manifest or configuration. The static data is exposed via the plugin interface and can be accessed through function calls, including those compatible with OpenAI’s function calling API.

Typical uses include providing product details, company contact information, sales promotions, coupon codes, or biographical background. The plugin supports both manifest-based and Django ORM-based initialization for flexible integration.

Key Features:

  • Returns static data defined in the plugin manifest or configuration.

  • Integrates with Django ORM for plugin data persistence.

  • Provides a tool definition compatible with OpenAI function calling.

  • Handles serialization and validation of static data.

  • Emits signals when the plugin is called and when it responds.

Parameters:

  • manifest (Optional[SAMStaticPlugin]) – Optional manifest object for plugin initialization.

  • args (tuple) – Additional positional arguments.

  • kwargs (dict) – Additional keyword arguments.

Note

Signals are emitted on plugin call and response for observability and integration.

See also

PluginBase PluginDataStatic PluginStaticSerializer OpenAI Function Calling Quickstart

Example Use Cases:

  • Providing static product information for a chatbot.

  • Supplying company contact details or promotional codes.

  • Returning biographical information about a company founder.

property ORMModelClass: Type[SAMStaticPlugin]

Return the Pydantic model class for the StaticPlugin manifest.

This property provides access to the Pydantic model class that defines the structure and validation rules for the StaticPlugin manifest. The returned class is typically SAMStaticPlugin, which encapsulates all necessary fields and constraints for a static plugin manifest.

Returns:

The Pydantic model class for the StaticPlugin manifest.

Return type:

Type[SAMStaticPlugin]

Notes

This property is useful for introspection, type checking, and for scenarios where you need to interact with the manifest model class directly (such as creating new instances or performing validation).

SAMPluginType

alias of SAMStaticPlugin

__init__(*args, manifest=None, **kwargs)[source]

Initialize a PluginBase instance.

Key features:

  • Lazy instantiation of class properties.

  • Supports multiple initialization methods including manifest, database model, and YAML/JSON.

  • Integrates with Django ORM for plugin metadata management.

  • Utilizes Pydantic models for manifest validation and serialization.

  • Provides hooks for plugin selection and prompt customization.

  • Ensures plugin readiness and validation before use.

  • Sends signals upon plugin creation or update.

This constructor supports several ways to create a plugin object:

  • Manifest-based initialization:

    Pass a Pydantic model instance via the manifest argument. This is the preferred method and is typically used when loading plugins from a manifest broker.

  • Database model initialization:

    Provide a Django model plugin ID via plugin_id or a PluginMeta instance via plugin_meta to load an existing plugin from the database.

  • YAML/JSON manifest initialization:

    Supply a YAML or JSON string (or dictionary) via the data argument to create a plugin from a manifest representation.

See ./data/sample-plugins/everlasting-gobstopper.yaml for an example manifest.

The constructor sets up internal state, initializes plugin properties, and triggers plugin creation or update logic as needed. It also sends signals when the plugin is ready.

Parameters:

  • user_profile (Optional[UserProfile]) – The user profile associated with the plugin.

  • selected (bool) – Whether the plugin is initially selected.

  • api_version (Optional[str]) – The API version for the plugin manifest.

  • manifest (Optional[SAMPluginCommon]) – A Pydantic model representing the plugin manifest.

  • plugin_id (Optional[int]) – The Django ORM plugin ID.

  • plugin_meta (Optional[PluginMeta]) – The Django ORM PluginMeta instance.

  • data (Union[dict[str, Any], str, None]) – YAML/JSON manifest as a string or dictionary.

  • name (Optional[str]) – The name of the plugin.

  • kwargs – Additional keyword arguments.

property custom_tool: dict[str, Any] | None

Return the plugin tool definition for OpenAI function calling.

See the OpenAI documentation: https://platform.openai.com/docs/assistants/tools/function-calling/quickstart

Example:

tool = {
    "type": "function",
    "function": {
        "name": "static_plugin_function",
        "description": "Static Plugin",
        "parameters": {
            "type": "object",
            "properties": {
                "inquiry_type": {
                    "type": "string",
                    "enum": ["contact", "biographical", "sales_promotions", "coupon_codes"],
                },
            },
            "required": ["inquiry_type"],
        },
    },
}
classmethod example_manifest(kwargs=None)[source]

use Pydantic models to generate an example manifest for a StaticPlugin.

Parameters:

kwargs (Optional[dict[str, Any]]) – Optional keyword arguments to customize the example manifest.

Returns:

An example manifest as a dictionary.

Return type:

Optional[dict[str, Any]]

Raises:

SmarterConfigurationError – If there is an error generating the example manifest.

See Also:

  • SAMStaticPlugin

  • SmarterApiVersions

  • SAMKeys

  • SAMMetadataKeys

  • SAMPluginCommonMetadataKeys

  • SAMPluginCommonMetadataClassValues

  • SAMPluginSpecKeys

  • SAMPluginCommonSpecSelectorKeys

  • SAMPluginCommonSpecSelectorKeyDirectiveValues

  • SAMPluginCommonSpecPromptKeys

  • SAMStaticPluginSpecDataKeys

property manifest: SAMStaticPlugin | None

Return the Pydantic model representation of the plugin manifest.

This property provides access to the plugin’s manifest as a validated Pydantic model (SAMStaticPlugin). If the manifest has not been set but the plugin is in a ready state, it will attempt to construct the manifest from the current plugin data using the to_json() method.

Returns:

The Pydantic model instance representing the plugin manifest, or None if unavailable.

Return type:

Optional[SAMStaticPlugin]

Notes

This property is useful for accessing structured, validated manifest data regardless of whether the plugin was initialized from a manifest or from Django ORM data.

property plugin_data: PluginDataStatic | None

Return the plugin data as a Django ORM instance.

This property provides access to the plugin’s data as a Django ORM model instance (PluginDataStatic). The returned object represents the persistent state of the plugin’s static data in the database.

The property handles several scenarios:

  • If the plugin was initialized from a manifest and is associated with a database record, it will construct the ORM instance from the manifest data.

  • If the plugin is already present in the database but not initialized from a manifest, it retrieves the existing ORM instance directly.

  • If neither a manifest nor a database record exists, it returns None.

This property is useful for interacting with the plugin’s data using Django’s ORM features, such as querying, updating, or serializing the static data.

Returns:

The Django ORM instance representing the plugin’s static data, or None if unavailable.

Return type:

Optional[PluginDataStatic]

Notes

This property abstracts the logic for resolving the plugin’s data source, ensuring that consumers of the property always receive a consistent ORM object when possible.

property plugin_data_class: Type[PluginDataStatic]

Return the Django ORM class used for static plugin data.

This property provides the class object for the Django model that represents the persistent storage of static plugin data. It is useful for introspection, type checking, and for scenarios where you need to interact with the model class directly (such as creating new instances, performing queries, or using Django’s ORM features programmatically).

The returned class is typically PluginDataStatic, which defines the schema for storing static data associated with this plugin type.

Returns:

The Django ORM class for static plugin data.

Return type:

Type[PluginDataStatic]

property plugin_data_django_model: dict[str, Any] | None

Transform the Pydantic model into a Django ORM-compatible dictionary.

This property generates a dictionary representation of the plugin’s static data, suitable for initializing or updating a Django ORM model instance (PluginDataStatic). The dictionary includes all fields required by the ORM model, such as the plugin reference, description, and static data payload.

The transformation is performed using the current Pydantic manifest model, if available. This allows for seamless conversion between validated manifest data and the persistent database representation used by Django.

Returns:

A dictionary containing the fields necessary to create or update a PluginDataStatic ORM instance, or None if the manifest is not available.

Return type:

Optional[dict[str, Any]]

Notes

This property is useful for bridging the gap between Pydantic-based manifest validation and Django ORM persistence, enabling consistent data handling across both systems.

property plugin_data_serializer: PluginStaticSerializer | None

Return the serializer instance for the plugin’s static data.

This property provides a serializer object (PluginStaticSerializer) that is initialized with the current plugin data. The serializer is responsible for converting the Django ORM model instance to and from native Python datatypes, as well as validating and serializing the static data for use in APIs or other interfaces.

If the serializer has not yet been created, it will be instantiated using the current plugin data. This ensures that the serializer always reflects the latest state of the plugin’s static data.

Returns:

The serializer instance for the plugin’s static data, or None if the plugin data is unavailable.

Return type:

Optional[PluginStaticSerializer]

Notes

The serializer is useful for tasks such as rendering the plugin data as JSON, validating incoming data, or preparing the data for use in API responses.

property plugin_data_serializer_class: Type[PluginStaticSerializer]

Return the plugin data serializer class.

This property provides direct access to the serializer class used for static plugin data. The serializer class is responsible for converting Django ORM model instances to and from native Python datatypes, as well as validating and serializing the static data for use in APIs or other interfaces.

Accessing the serializer class is useful when you need to instantiate a new serializer, perform type checks, or customize serialization behavior for static plugin data.

Returns:

The serializer class for static plugin data.

Return type:

Type[PluginStaticSerializer]

Notes

This property does not return an instance, but rather the class itself, allowing for flexible instantiation and extension in advanced use cases.

tool_call_fetch_plugin_response(function_args)[source]

Fetch a response from the StaticPlugin based on the provided inquiry type.

This method retrieves the value associated with the specified inquiry_type from the plugin’s static data. It is intended for use with function calling interfaces, such as those provided by OpenAI, where the inquiry type is passed as an argument and the corresponding static data is returned as a JSON-encoded string.

The method performs several validation steps:

  • Ensures that the inquiry_type argument is present and is a string.

  • Verifies that the plugin is in a ready state and that plugin data is available.

  • Emits signals when the plugin is called and when it responds.

  • Looks up the value for the given inquiry type in the plugin’s static data.

  • Serializes the result to a JSON string before returning.

  • Raises detailed errors if any step fails, including missing inquiry types, serialization issues, or invalid data.

Parameters:

function_args (dict[str, Any]) – A dictionary of arguments, expected to include the key inquiry_type specifying which static data to fetch.

Returns:

The JSON-encoded string corresponding to the requested inquiry type.

Return type:

str

Raises:

SmarterPluginError – If the inquiry type is missing, not a string, not found in the static data, or if the plugin is not ready or lacks data. Also raised if the return value cannot be serialized to JSON or is not a string.

Notes

This method is typically used as the handler for function calling APIs, enabling external systems to retrieve specific pieces of static information from the plugin in a robust and validated manner.

Return type:

Union[dict, list, str]

smarter.apps.plugin.plugin.static.should_log(level)[source]

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