Add experimental Python plugin development API

.github/workflows/test.yml

@@ -41,7 +41,8 @@ jobs:
       max-parallel: 8
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
-        # There's no platform specific SDK code, but explicitly check Windows anyway
+        # There's no platform specific SDK code, but explicitly check Windows
+        # to ensure there aren't any inadvertent POSIX-only assumptions
         os: [ubuntu-22.04, windows-2022]
 
     # Check https://github.com/actions/action-versions/tree/main/config/actions

examples/plugins/dice-tool/README.md

@@ -0,0 +1,3 @@
+# `lmstudio/pydice`
+
+TODO: Example Python tools provider plugin

examples/plugins/dice-tool/manifest.json

@@ -0,0 +1,7 @@
+{
+  "type": "plugin",
+  "runner": "python",
+  "owner": "lmstudio",
+  "name": "py-dice-tool",
+  "revision": 2
+}

examples/plugins/dice-tool/src/plugin.py

@@ -0,0 +1,3 @@
+"""Example plugin that provide dice rolling tools."""
+
+# Not yet implemented, currently used to check plugins with no hooks defined

examples/plugins/prompt-prefix/README.md

@@ -0,0 +1,6 @@
+# `lmstudio/pyprompt`
+
+Python prompt preprocessing plugin example
+
+Note: there's no `python` runner in LM Studio yet, so use
+`python -m lmstudio.plugin --dev path/to/plugin` to run a dev instance

examples/plugins/prompt-prefix/manifest.json

@@ -0,0 +1,7 @@
+{
+  "type": "plugin",
+  "runner": "python",
+  "owner": "lmstudio",
+  "name": "prompt-prefix",
+  "revision": 1
+}

examples/plugins/prompt-prefix/src/plugin.py

@@ -0,0 +1,76 @@
+"""Example plugin that adds a prefix to all user prompts."""
+
+import asyncio
+
+from lmstudio.plugin import BaseConfigSchema, PromptPreprocessorController, config_field
+from lmstudio import UserMessage, UserMessageDict, TextDataDict
+
+
+# Assigning ConfigSchema = SomeOtherSchemaClass also works
+class ConfigSchema(BaseConfigSchema):
+    """The name 'ConfigSchema' implicitly registers this as the per-chat plugin config schema."""
+
+    prefix: str = config_field(
+        label="Prefix to insert",
+        hint="This text will be inserted at the start of all user prompts",
+        default="And now for something completely different: ",
+    )
+
+
+# Assigning GlobalConfigSchema = SomeOtherGlobalSchemaClass also works
+class GlobalConfigSchema(BaseConfigSchema):
+    """The name 'GlobalConfigSchema' implicitly registers this as the global plugin config schema."""
+
+    enable_inplace_status_demo: bool = config_field(
+        label="Enable in-place status demo",
+        hint="The plugin will run an in-place task status updating demo when invoked",
+        default=True,
+    )
+    inplace_status_duration: float = config_field(
+        label="In-place status total duration (s)",
+        hint="The number of seconds to spend displaying the in-place task status update",
+        default=5.0,
+    )
+
+
+# Assigning preprocess_prompt = some_other_callable also works
+async def preprocess_prompt(
+    ctl: PromptPreprocessorController[ConfigSchema, GlobalConfigSchema],
+    message: UserMessage,
+) -> UserMessageDict | None:
+    """Naming the function 'preprocess_prompt' implicitly registers it."""
+    if ctl.global_config.enable_inplace_status_demo:
+        # Run an in-place status prompt update demonstration
+        status_block = await ctl.notify_start("Starting task (shows a static icon).")
+        status_updates = (
+            (status_block.notify_working, "Task in progress (shows a dynamic icon)."),
+            (status_block.notify_waiting, "Task is blocked (shows a static icon)."),
+            (status_block.notify_error, "Reporting an error status."),
+            (status_block.notify_canceled, "Reporting cancellation."),
+            (
+                status_block.notify_done,
+                "In-place status update demonstration completed.",
+            ),
+        )
+        status_duration = ctl.global_config.inplace_status_duration / len(
+            status_updates
+        )
+        async with status_block.notify_aborted("Task genuinely cancelled."):
+            for notification, status_text in status_updates:
+                await asyncio.sleep(status_duration)
+                await notification(status_text)
+
+    modified_message = message.to_dict()
+    # Add a prefix to all user messages
+    prefix_text = ctl.plugin_config.prefix
+    prefix: TextDataDict = {
+        "type": "text",
+        "text": prefix_text,
+    }
+    modified_message["content"] = [prefix, *modified_message["content"]]
+    # Demonstrate simple completion status reporting for non-blocking operations
+    await ctl.notify_done(f"Added prefix {prefix_text!r} to user message.")
+    return modified_message
+
+
+print(f"{__name__} initialized from {__file__}")

sdk-schema/sync-sdk-schema.py

@@ -363,6 +363,18 @@ def _infer_schema_unions() -> None:
     "LlmChannelPredictCreationParameterDict": "PredictionChannelRequestDict",
     "RepositoryChannelDownloadModelCreationParameter": "DownloadModelChannelRequest",
     "RepositoryChannelDownloadModelCreationParameterDict": "DownloadModelChannelRequestDict",
+    # Prettier plugin channel message names
+    "PluginsChannelSetPromptPreprocessorToClientPacketPreprocess": "PromptPreprocessingRequest",
+    "PluginsChannelSetPromptPreprocessorToClientPacketPreprocessDict": "PromptPreprocessingRequestDict",
+    "PluginsChannelSetPromptPreprocessorToServerPacketAborted": "PromptPreprocessingAborted",
+    "PluginsChannelSetPromptPreprocessorToServerPacketAbortedDict": "PromptPreprocessingAbortedDict",
+    "PluginsChannelSetPromptPreprocessorToServerPacketComplete": "PromptPreprocessingComplete",
+    "PluginsChannelSetPromptPreprocessorToServerPacketCompleteDict": "PromptPreprocessingCompleteDict",
+    "PluginsChannelSetPromptPreprocessorToServerPacketError": "PromptPreprocessingError",
+    "PluginsChannelSetPromptPreprocessorToServerPacketErrorDict": "PromptPreprocessingErrorDict",
+    # Prettier config handling type names
+    "LlmRpcGetLoadConfigReturns": "SerializedKVConfigSettings",
+    "LlmRpcGetLoadConfigReturnsDict": "SerializedKVConfigSettingsDict",
 }
 
 

src/lmstudio/_kv_config.py

@@ -40,6 +40,7 @@
     LlmSplitStrategy,
     LlmStructuredPredictionSetting,
     LlmStructuredPredictionSettingDict,
+    SerializedKVConfigSettings,
 )
 
 
@@ -324,7 +325,7 @@ def _invert_config_keymap(from_server: FromServerKeymap) -> ToServerKeymap:
 )
 
 
-def dict_from_kvconfig(config: KvConfig) -> DictObject:
+def dict_from_kvconfig(config: KvConfig | SerializedKVConfigSettings) -> DictObject:
     return {kv.key: kv.value for kv in config.fields}