Static LLMTool Plugin

Technical References

A Plugin that returns static data stored in the Plugin itself.

Note

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

  1. Smarter Static Plugin: The plugin that defines the static data, organized by inquiry type, that it returns to the LLM.

  2. Smarter LLMClient: The prompting resource (LLMClient, Agent, Workflow unit, etcetera) that includes the Static Plugin.

Note

The structure of spec.data.staticData has semantic meaning. Its keys are the inquiry types that the LLM can request, and each key’s value is the data returned for that inquiry type. Keys of nested dicts are inquiry types too. In the example manifest below, the LLM can request contact, biographical, salesPromotions or couponCodes.

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 llmclient 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-6-luna
    temperature: 1.0
    maxTokens: 256
  data:
    # ---------------------------------------------------------------------------
    # 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 LLMClient Manifest
apiVersion: smarter.sh/v1
kind: LLMClient
metadata:
  description: "An example llmclient 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:
    prompt:
      appAssistant: Lawrence
      appExamplePrompts:
      - What is the weather in San Francisco?
      - What is an Everlasting Gobstopper?
      - example function calling configuration
      appFileAttachment: false
      appInfoUrl: https://smarter.sh
      appName: Smarter Demo
      appPlaceholder: Ask me anything...
      appWelcomeMessage: Welcome to the Smarter demo!
      customDomain: null
      defaultMaxTokens: 4096
      defaultModel: gpt-6-luna
      defaultSystemRole: You are a helpful llmclient. 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.

        Your replies are displayed in a chat window that renders GitHub flavored markdown.
        Use **bold** for key facts, bulleted lists for several items, and a small table when
        you present structured data from a function. When a function returns
        an image url, show the image with markdown image syntax, ![description](https://...).
      defaultTemperature: 1.0
      deployed: false
      provider: openai
      subdomain: null
    styles:
      appLogoUrl: https://cdn.smarter.sh/images/logo/smarter-crop.png
      appBackgroundImageUrl: https://cdn.smarter.sh/cms/img/techdots.png
      assistantAvatarUrl: https://cdn.smarter.sh/images/llmclients/example/assistant.png
      googleFont: Montserrat
      borderRadius: 14px
      conversationHeader:
        backgroundColor: '#f15a29'
        color: '#ffffff'
        infoColor: '#ffe3d1'
      messageList:
        backgroundColor: rgba(255, 255, 255, 0.7)
        color: '#3a2a1a'
      incomingMessage:
        backgroundColor: '#ffffff'
        color: '#3a2a1a'
        borderColor: '#f7c9b5'
      outgoingMessage:
        backgroundColor: '#fdb913'
        color: '#3a2a00'
      buttons:
        color: '#f15a29'
      typingIndicator:
        color: '#f15a29'
  functions:
    - get_current_weather
  plugins:
    - everlasting_gobstopper
    - example_configuration
    - image_search
  guardrails:
    - prompt_injection_keyword_input
    - moderation_input
    - moderation_output
class smarter.apps.llmtool.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 (SAMStaticPlugin | None) – 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 an llmclient.

  • Supplying company contact details or promotional codes.

  • Returning biographical information about a company founder.

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 (SAMStaticPlugin | None) – 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[SmarterDictType, 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.

The tool takes a single required parameter, inquiry_type, whose enum is inquiry_types. The enum is omitted if the plugin has no inquiry types, since a null enum is not a valid JSON schema.

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

Returns:

The tool definition, or None if the plugin is not ready.

Return type:

Optional[SmarterDictType]

Example:

tool = {
    "type": "function",
    "function": {
        "name": "smarter_plugin_0000000042",
        "description": "Get additional information about the Everlasting Gobstopper ...",
        "parameters": {
            "type": "object",
            "properties": {
                "inquiry_type": {
                    "type": "string",
                    "enum": ["contact", "biographical", "salesPromotions", "couponCodes"],
                },
            },
            "required": ["inquiry_type"],
        },
    },
}
classmethod example_manifest(kwargs=None)[source]

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

Parameters:

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

Returns:

An example manifest as a dictionary.

Return type:

dict[str, Any] | None

Raises:

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

See Also:

  • SAMStaticPlugin

  • SmarterApiVersions

  • SAMKeys

  • SAMMetadataKeys

  • SAMPluginCommonMetadataKeys

  • SAMPluginCommonMetadataClassValues

  • SAMPluginSpecKeys

  • SAMPluginCommonSpecSelectorKeys

  • SAMPluginCommonSpecSelectorKeyDirectiveValues

  • SAMPluginCommonSpecPromptKeys

  • SAMStaticPluginSpecDataKeys

classmethod find_inquiry_value(data, inquiry_type)[source]

Find the value of an inquiry type in the static data.

Keys at the current level take precedence, after which nested dicts are searched depth-first. This mirrors how inquiry_types are collected, so that every advertised inquiry type can be resolved.

Parameters:

  • data (dict[str, Any]) – The static data.

  • inquiry_type (str) – The inquiry type to find.

Returns:

A tuple of (found, value). found distinguishes a missing inquiry type from one whose value is None.

Return type:

tuple[bool, Any]

Example:

StaticPlugin.find_inquiry_value({"hours": {"weekdays": "9am - 5pm"}}, "weekdays")
# (True, '9am - 5pm')
property inquiry_types: list[str]

Return the inquiry types that the LLM can request from this plugin.

The inquiry types are the keys of staticData, including the keys of nested dicts, without duplicates. Keys inside lists are not inquiry types. Their order is the order in which the database returns the static data. They are presented to the LLM as the enum of the inquiry_type function parameter, and each one can be resolved by tool_call_fetch_plugin_response().

Returns:

The inquiry types, or an empty list if the plugin data is not available.

Return type:

list[str]

Example:

staticData:
  contact:
    - name: Willy Wonka
  biographical: >
    Willy Wonka is a fictional character ...
  hours:
    weekdays: 9am - 5pm
    weekends: closed

plugin.inquiry_types
# ['contact', 'biographical', 'hours', 'weekdays', 'weekends']
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[SmarterDictType]

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.

classmethod to_tool_response(value)[source]

Convert a static data value to a tool call response.

  • dicts and lists are returned as-is.

  • strings containing a JSON object or array are decoded. All other strings are returned as-is.

  • None is returned as an empty string.

  • all other scalars (numbers, booleans) are returned as their JSON string representation.

Parameters:

value (Any) – A value from the static data.

Returns:

The tool call response.

Return type:

dict[str, Any] | list | str

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 the handler for the OpenAI function calling tool defined by custom_tool.

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

The method:

  • Accepts the arguments as a dict, or as the JSON string sent by OpenAI.

  • 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 plugin_called when the plugin is called and plugin_responded when it responds.

  • Looks up the value for the inquiry type in the static data, including in nested dicts.

  • Converts the value to a dict, list or str. See to_tool_response().

Example tool call payload:

"tool_calls": [
    {
        "id": "call_1Ucn2R5WmBh7TtoE197SsP3p",
        "function": {
            "arguments": "{"inquiry_type":"couponCodes"}",  # these are the function_args
            "name": "smarter_plugin_0000004468"
        },
        "type": "function"
    }
]
Parameters:

function_args (dict[str, Any] | str | None) – The function arguments, which must include inquiry_type.

Returns:

The static data for the inquiry type.

Return type:

dict[str, Any] | list | str

Raises:

SmarterPluginError – If the arguments are malformed, the inquiry type is missing, not a string or not found in the static data, or if the plugin is not ready or lacks data.

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

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