@quilltap/plugin-utils 1.6.2 → 1.7.1

package/README.md

@@ -205,6 +205,49 @@ export const plugin = createRoleplayTemplatePlugin({
 | `validateTemplateConfig(template)` | Validate an individual template configuration |
 | `validateRoleplayTemplatePlugin(plugin)` | Validate a complete roleplay template plugin |
 
+### System Prompt Plugin Utilities
+
+Create system prompt plugins that provide character prompt templates from `.md` files:
+
+```typescript
+import { createSystemPromptPlugin } from '@quilltap/plugin-utils';
+import type { SystemPromptData } from '@quilltap/plugin-types';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+function loadPrompts(): SystemPromptData[] {
+  const promptsDir = join(dirname(__filename), 'prompts');
+  return readdirSync(promptsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(file => {
+      const name = file.replace(/\.md$/i, '');
+      const parts = name.split('_');
+      const category = parts.pop()!;
+      const modelHint = parts.join('_');
+      return {
+        name,
+        content: readFileSync(join(promptsDir, file), 'utf-8'),
+        modelHint,
+        category,
+      };
+    });
+}
+
+export const plugin = createSystemPromptPlugin({
+  metadata: {
+    pluginId: 'my-prompts',
+    displayName: 'My System Prompts',
+    version: '1.0.0',
+  },
+  prompts: loadPrompts(),
+});
+```
+
+| Function | Description |
+|----------|-------------|
+| `createSystemPromptPlugin(options)` | Create a system prompt plugin with validation |
+| `validateSystemPromptPlugin(plugin)` | Validate a complete system prompt plugin |
+
 ## Example: Complete Plugin Provider
 
 ```typescript

package/dist/index.d.mts

@@ -3,6 +3,7 @@ export { T as ToolCallFormat, a as ToolConvertTarget, b as applyDescriptionLimit
 export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger } from './logging/index.mjs';
 export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './providers/index.mjs';
 export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions, createRoleplayTemplatePlugin, createSingleTemplatePlugin, validateRoleplayTemplatePlugin, validateTemplateConfig } from './roleplay-templates/index.mjs';
+export { CreateSystemPromptPluginOptions, createSystemPromptPlugin, validateSystemPromptPlugin } from './system-prompts/index.mjs';
 export { isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl } from './host-rewrite.mjs';
 import 'openai';
 
@@ -134,6 +135,6 @@ declare function getQuilltapUserAgent(): string;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.6.1";
+declare const PLUGIN_UTILS_VERSION = "1.7.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { T as ToolCallFormat, a as ToolConvertTarget, b as applyDescriptionLimit
 export { PluginLoggerWithChild, __clearCoreLoggerFactory, __injectCoreLoggerFactory, createPluginLogger, getLogLevelFromEnv, hasCoreLogger } from './logging/index.js';
 export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './providers/index.js';
 export { CreateRoleplayTemplatePluginOptions, CreateSingleTemplatePluginOptions, createRoleplayTemplatePlugin, createSingleTemplatePlugin, validateRoleplayTemplatePlugin, validateTemplateConfig } from './roleplay-templates/index.js';
+export { CreateSystemPromptPluginOptions, createSystemPromptPlugin, validateSystemPromptPlugin } from './system-prompts/index.js';
 export { isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl } from './host-rewrite.js';
 import 'openai';
 
@@ -134,6 +135,6 @@ declare function getQuilltapUserAgent(): string;
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.6.1";
+declare const PLUGIN_UTILS_VERSION = "1.7.0";
 
 export { BUILTIN_TOOL_NAMES, PLUGIN_UTILS_VERSION, __clearQuilltapVersion, __injectQuilltapVersion, getBuiltinToolNames, getQuilltapUserAgent, getQuilltapVersion };

package/dist/index.js

@@ -51,6 +51,7 @@ __export(src_exports, {
   createPluginLogger: () => createPluginLogger,
   createRoleplayTemplatePlugin: () => createRoleplayTemplatePlugin,
   createSingleTemplatePlugin: () => createSingleTemplatePlugin,
+  createSystemPromptPlugin: () => createSystemPromptPlugin,
   detectToolCallFormat: () => detectToolCallFormat,
   getBuiltinToolNames: () => getBuiltinToolNames,
   getLogLevelFromEnv: () => getLogLevelFromEnv,
@@ -66,6 +67,7 @@ __export(src_exports, {
   resolveHostGateway: () => resolveHostGateway,
   rewriteLocalhostUrl: () => rewriteLocalhostUrl,
   validateRoleplayTemplatePlugin: () => validateRoleplayTemplatePlugin,
+  validateSystemPromptPlugin: () => validateSystemPromptPlugin,
   validateTemplateConfig: () => validateTemplateConfig
 });
 module.exports = __toCommonJS(src_exports);
@@ -808,6 +810,80 @@ function validateRoleplayTemplatePlugin(plugin) {
   return true;
 }
 
+// src/system-prompts/builder.ts
+function createSystemPromptPlugin(options) {
+  const { metadata, prompts, initialize } = options;
+  if (prompts.length === 0) {
+    throw new Error("At least one system prompt is required");
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const prompt of prompts) {
+    if (!prompt.name || prompt.name.trim() === "") {
+      throw new Error("Prompt name is required");
+    }
+    if (!prompt.content || prompt.content.trim() === "") {
+      throw new Error(`Prompt "${prompt.name}" requires content`);
+    }
+    if (!prompt.modelHint || prompt.modelHint.trim() === "") {
+      throw new Error(`Prompt "${prompt.name}" requires a modelHint`);
+    }
+    if (!prompt.category || prompt.category.trim() === "") {
+      throw new Error(`Prompt "${prompt.name}" requires a category`);
+    }
+    if (names.has(prompt.name)) {
+      throw new Error(`Duplicate prompt name: "${prompt.name}"`);
+    }
+    names.add(prompt.name);
+  }
+  const plugin = {
+    metadata,
+    prompts
+  };
+  if (initialize) {
+    plugin.initialize = async () => {
+      await initialize();
+    };
+  }
+  return plugin;
+}
+function validateSystemPromptPlugin(plugin) {
+  if (!plugin.metadata) {
+    throw new Error("Plugin metadata is required");
+  }
+  if (!plugin.metadata.pluginId || plugin.metadata.pluginId.trim() === "") {
+    throw new Error("Plugin metadata.pluginId is required");
+  }
+  if (!/^[a-z0-9-]+$/.test(plugin.metadata.pluginId)) {
+    throw new Error("Plugin pluginId must be lowercase alphanumeric with hyphens only");
+  }
+  if (!plugin.metadata.displayName || plugin.metadata.displayName.trim() === "") {
+    throw new Error("Plugin metadata.displayName is required");
+  }
+  if (!plugin.prompts || !Array.isArray(plugin.prompts) || plugin.prompts.length === 0) {
+    throw new Error("Plugin must have at least one prompt");
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const prompt of plugin.prompts) {
+    if (!prompt.name || prompt.name.trim() === "") {
+      throw new Error("Prompt name is required");
+    }
+    if (!prompt.content || prompt.content.trim() === "") {
+      throw new Error(`Prompt "${prompt.name}" requires content`);
+    }
+    if (!prompt.modelHint || prompt.modelHint.trim() === "") {
+      throw new Error(`Prompt "${prompt.name}" requires a modelHint`);
+    }
+    if (!prompt.category || prompt.category.trim() === "") {
+      throw new Error(`Prompt "${prompt.name}" requires a category`);
+    }
+    if (names.has(prompt.name)) {
+      throw new Error(`Duplicate prompt name: "${prompt.name}"`);
+    }
+    names.add(prompt.name);
+  }
+  return true;
+}
+
 // src/builtin-tools.ts
 var BUILTIN_TOOL_NAMES = /* @__PURE__ */ new Set([
   "generate_image",
@@ -956,7 +1032,7 @@ function rewriteLocalhostUrl(url) {
 }
 
 // src/index.ts
-var PLUGIN_UTILS_VERSION = "1.6.1";
+var PLUGIN_UTILS_VERSION = "1.7.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUILTIN_TOOL_NAMES,
@@ -980,6 +1056,7 @@ var PLUGIN_UTILS_VERSION = "1.6.1";
   createPluginLogger,
   createRoleplayTemplatePlugin,
   createSingleTemplatePlugin,
+  createSystemPromptPlugin,
   detectToolCallFormat,
   getBuiltinToolNames,
   getLogLevelFromEnv,
@@ -995,6 +1072,7 @@ var PLUGIN_UTILS_VERSION = "1.6.1";
   resolveHostGateway,
   rewriteLocalhostUrl,
   validateRoleplayTemplatePlugin,
+  validateSystemPromptPlugin,
   validateTemplateConfig
 });
 //# sourceMappingURL=index.js.map