@quilltap/plugin-utils 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to @quilltap/plugin-utils will be documented in this file.
 
+## [1.2.0] - 2025-12-31
+
+### Added
+
+- **Roleplay Template Plugin Utilities**
+  - `createRoleplayTemplatePlugin()` - Create roleplay template plugins with full control
+  - `createSingleTemplatePlugin()` - Simplified helper for single-template plugins
+  - `validateTemplateConfig()` - Validate individual template configurations
+  - `validateRoleplayTemplatePlugin()` - Validate complete roleplay template plugins
+  - `CreateRoleplayTemplatePluginOptions` - Options interface for full control
+  - `CreateSingleTemplatePluginOptions` - Simplified options for single templates
+
+- **New Export Path**
+  - `@quilltap/plugin-utils/roleplay-templates` - Direct import path for roleplay template utilities
+
+## [1.1.0] - 2025-12-30
+
+### Added
+
+- **OpenAI-Compatible Provider Base Class**
+  - `OpenAICompatibleProvider` - Reusable base class for OpenAI-compatible LLM providers
+  - `OpenAICompatibleProviderConfig` - Configuration interface for customizing providers
+  - Supports streaming and non-streaming chat completions
+  - Configurable API key requirements (`requireApiKey` option)
+  - Customizable provider name for logging (`providerName` option)
+  - Customizable attachment error messages (`attachmentErrorMessage` option)
+  - Includes API key validation and model listing
+  - Uses the plugin logger bridge for consistent logging
+  - Peer dependency on `openai` package (optional, only needed if using this provider)
+
+- **New Export Path**
+  - `@quilltap/plugin-utils/providers` - Direct import path for provider base classes
+
 ## [1.0.0] - 2025-12-30
 
 ### Added

package/README.md

@@ -110,6 +110,101 @@ When running standalone:
 | `createConsoleLogger(prefix, minLevel?)` | Create a standalone console logger |
 | `createNoopLogger()` | Create a no-op logger |
 
+### OpenAI-Compatible Provider Base Class
+
+Create custom LLM providers for OpenAI-compatible APIs with minimal code:
+
+```typescript
+import { OpenAICompatibleProvider } from '@quilltap/plugin-utils';
+
+// Create a provider for any OpenAI-compatible API
+export class MyLLMProvider extends OpenAICompatibleProvider {
+  constructor() {
+    super({
+      baseUrl: 'https://api.my-llm-service.com/v1',
+      providerName: 'MyLLM',
+      requireApiKey: true,
+      attachmentErrorMessage: 'MyLLM does not support file attachments',
+    });
+  }
+}
+```
+
+This gives you a complete `LLMProvider` implementation with:
+- Streaming and non-streaming chat completions
+- API key validation
+- Model listing
+- Proper error handling and logging
+
+**Configuration Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | (required) | API endpoint URL with version path |
+| `providerName` | `string` | `'OpenAICompatible'` | Name used in log messages |
+| `requireApiKey` | `boolean` | `false` | Whether API key is mandatory |
+| `attachmentErrorMessage` | `string` | (default message) | Error shown for attachment failures |
+
+**Note:** Requires `openai` as a peer dependency:
+```bash
+npm install openai
+```
+
+### Roleplay Template Plugin Utilities
+
+Create roleplay template plugins with built-in validation and logging:
+
+```typescript
+import { createSingleTemplatePlugin } from '@quilltap/plugin-utils';
+
+// Simple single-template plugin
+export const plugin = createSingleTemplatePlugin({
+  templateId: 'my-rp-format',
+  displayName: 'My RP Format',
+  description: 'A custom roleplay formatting style',
+  systemPrompt: `[FORMATTING INSTRUCTIONS]
+1. DIALOGUE: Use quotation marks
+2. ACTIONS: Use asterisks *like this*
+3. THOUGHTS: Use angle brackets <like this>`,
+  tags: ['custom', 'roleplay'],
+  enableLogging: true,
+});
+```
+
+For plugins providing multiple templates:
+
+```typescript
+import { createRoleplayTemplatePlugin } from '@quilltap/plugin-utils';
+
+export const plugin = createRoleplayTemplatePlugin({
+  metadata: {
+    templateId: 'rp-format-pack',
+    displayName: 'RP Format Pack',
+    description: 'A collection of roleplay formats',
+  },
+  templates: [
+    {
+      name: 'Screenplay',
+      description: 'Screenplay-style formatting',
+      systemPrompt: '...',
+    },
+    {
+      name: 'Novel',
+      description: 'Novel-style prose',
+      systemPrompt: '...',
+    },
+  ],
+  enableLogging: true,
+});
+```
+
+| Function | Description |
+|----------|-------------|
+| `createRoleplayTemplatePlugin(options)` | Create a plugin with full control over metadata and templates |
+| `createSingleTemplatePlugin(options)` | Simplified helper for plugins with a single template |
+| `validateTemplateConfig(template)` | Validate an individual template configuration |
+| `validateRoleplayTemplatePlugin(plugin)` | Validate a complete roleplay template plugin |
+
 ## Example: Complete Plugin Provider
 
 ```typescript

package/dist/index.d.mts

@@ -2,6 +2,7 @@ export { AnthropicToolDefinition, GoogleToolDefinition, LogContext, LogLevel, Op
 export { ToolCallFormat, ToolConvertTarget, applyDescriptionLimit, convertFromAnthropicFormat, convertFromGoogleFormat, convertToAnthropicFormat, convertToGoogleFormat, convertToolTo, convertToolsTo, detectToolCallFormat, hasToolCalls, parseAnthropicToolCalls, parseGoogleToolCalls, parseOpenAIToolCalls, parseToolCalls } from './tools/index.mjs';
 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';
 
 /**
  * @quilltap/plugin-utils
@@ -23,6 +24,6 @@ export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './prov
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.1.0";
+declare const PLUGIN_UTILS_VERSION = "1.2.0";
 
 export { PLUGIN_UTILS_VERSION };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { AnthropicToolDefinition, GoogleToolDefinition, LogContext, LogLevel, Op
 export { ToolCallFormat, ToolConvertTarget, applyDescriptionLimit, convertFromAnthropicFormat, convertFromGoogleFormat, convertToAnthropicFormat, convertToGoogleFormat, convertToolTo, convertToolsTo, detectToolCallFormat, hasToolCalls, parseAnthropicToolCalls, parseGoogleToolCalls, parseOpenAIToolCalls, parseToolCalls } from './tools/index.js';
 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';
 
 /**
  * @quilltap/plugin-utils
@@ -23,6 +24,6 @@ export { OpenAICompatibleProvider, OpenAICompatibleProviderConfig } from './prov
  * Version of the plugin-utils package.
  * Can be used at runtime to check compatibility.
  */
-declare const PLUGIN_UTILS_VERSION = "1.1.0";
+declare const PLUGIN_UTILS_VERSION = "1.2.0";
 
 export { PLUGIN_UTILS_VERSION };

package/dist/index.js

@@ -44,6 +44,8 @@ __export(src_exports, {
   createConsoleLogger: () => import_plugin_types.createConsoleLogger,
   createNoopLogger: () => import_plugin_types.createNoopLogger,
   createPluginLogger: () => createPluginLogger,
+  createRoleplayTemplatePlugin: () => createRoleplayTemplatePlugin,
+  createSingleTemplatePlugin: () => createSingleTemplatePlugin,
   detectToolCallFormat: () => detectToolCallFormat,
   getLogLevelFromEnv: () => getLogLevelFromEnv,
   hasCoreLogger: () => hasCoreLogger,
@@ -51,7 +53,9 @@ __export(src_exports, {
   parseAnthropicToolCalls: () => parseAnthropicToolCalls,
   parseGoogleToolCalls: () => parseGoogleToolCalls,
   parseOpenAIToolCalls: () => parseOpenAIToolCalls,
-  parseToolCalls: () => parseToolCalls
+  parseToolCalls: () => parseToolCalls,
+  validateRoleplayTemplatePlugin: () => validateRoleplayTemplatePlugin,
+  validateTemplateConfig: () => validateTemplateConfig
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -506,37 +510,53 @@ var OpenAICompatibleProvider = class {
         stream_options: { include_usage: true }
       });
       let chunkCount = 0;
+      let accumulatedUsage = null;
+      let finalFinishReason = null;
       for await (const chunk of stream) {
         chunkCount++;
         const content = chunk.choices[0]?.delta?.content;
         const finishReason = chunk.choices[0]?.finish_reason;
         const hasUsage = chunk.usage;
-        if (content && !(finishReason && hasUsage)) {
-          yield {
-            content,
-            done: false
-          };
+        if (finishReason) {
+          finalFinishReason = finishReason;
         }
-        if (finishReason && hasUsage) {
-          this.logger.debug("Stream completed", {
+        if (hasUsage) {
+          accumulatedUsage = {
+            prompt_tokens: chunk.usage?.prompt_tokens,
+            completion_tokens: chunk.usage?.completion_tokens,
+            total_tokens: chunk.usage?.total_tokens
+          };
+          this.logger.debug("Received usage data in stream", {
             context: `${this.providerName}Provider.streamMessage`,
-            finishReason,
-            chunks: chunkCount,
             promptTokens: chunk.usage?.prompt_tokens,
             completionTokens: chunk.usage?.completion_tokens
           });
+        }
+        if (content) {
           yield {
-            content: "",
-            done: true,
-            usage: {
-              promptTokens: chunk.usage?.prompt_tokens ?? 0,
-              completionTokens: chunk.usage?.completion_tokens ?? 0,
-              totalTokens: chunk.usage?.total_tokens ?? 0
-            },
-            attachmentResults
+            content,
+            done: false
           };
         }
       }
+      this.logger.debug("Stream completed", {
+        context: `${this.providerName}Provider.streamMessage`,
+        finishReason: finalFinishReason,
+        chunks: chunkCount,
+        promptTokens: accumulatedUsage?.prompt_tokens,
+        completionTokens: accumulatedUsage?.completion_tokens,
+        hasUsage: !!accumulatedUsage
+      });
+      yield {
+        content: "",
+        done: true,
+        usage: accumulatedUsage ? {
+          promptTokens: accumulatedUsage.prompt_tokens ?? 0,
+          completionTokens: accumulatedUsage.completion_tokens ?? 0,
+          totalTokens: accumulatedUsage.total_tokens ?? 0
+        } : void 0,
+        attachmentResults
+      };
     } catch (error) {
       this.logger.error(
         `${this.providerName} API error in streamMessage`,
@@ -628,8 +648,130 @@ var OpenAICompatibleProvider = class {
   }
 };
 
+// src/roleplay-templates/builder.ts
+function createRoleplayTemplatePlugin(options) {
+  const { metadata, templates, initialize, enableLogging = false } = options;
+  const templateArray = Array.isArray(templates) ? templates : [templates];
+  if (templateArray.length === 0) {
+    throw new Error("At least one template is required");
+  }
+  for (const template of templateArray) {
+    if (!template.name || template.name.trim() === "") {
+      throw new Error("Template name is required");
+    }
+    if (!template.systemPrompt || template.systemPrompt.trim() === "") {
+      throw new Error(`Template "${template.name}" requires a systemPrompt`);
+    }
+  }
+  const plugin = {
+    metadata: {
+      ...metadata,
+      // Ensure tags from templates are included in metadata if not already set
+      tags: metadata.tags ?? Array.from(
+        new Set(templateArray.flatMap((t) => t.tags ?? []))
+      )
+    },
+    templates: templateArray
+  };
+  if (initialize || enableLogging) {
+    plugin.initialize = async () => {
+      if (enableLogging) {
+        const logger = createPluginLogger(metadata.templateId);
+        logger.debug("Roleplay template plugin loaded", {
+          context: "init",
+          templateId: metadata.templateId,
+          displayName: metadata.displayName,
+          templateCount: templateArray.length,
+          templateNames: templateArray.map((t) => t.name)
+        });
+      }
+      if (initialize) {
+        await initialize();
+      }
+    };
+  }
+  return plugin;
+}
+function createSingleTemplatePlugin(options) {
+  const {
+    templateId,
+    displayName,
+    description,
+    systemPrompt,
+    author,
+    tags,
+    version,
+    initialize,
+    enableLogging
+  } = options;
+  return createRoleplayTemplatePlugin({
+    metadata: {
+      templateId,
+      displayName,
+      description,
+      author,
+      tags,
+      version
+    },
+    templates: {
+      name: displayName,
+      description,
+      systemPrompt,
+      tags
+    },
+    initialize,
+    enableLogging
+  });
+}
+function validateTemplateConfig(template) {
+  if (!template.name || template.name.trim() === "") {
+    throw new Error("Template name is required");
+  }
+  if (template.name.length > 100) {
+    throw new Error("Template name must be 100 characters or less");
+  }
+  if (!template.systemPrompt || template.systemPrompt.trim() === "") {
+    throw new Error("Template systemPrompt is required");
+  }
+  if (template.description && template.description.length > 500) {
+    throw new Error("Template description must be 500 characters or less");
+  }
+  if (template.tags) {
+    if (!Array.isArray(template.tags)) {
+      throw new Error("Template tags must be an array");
+    }
+    for (const tag of template.tags) {
+      if (typeof tag !== "string") {
+        throw new Error("All tags must be strings");
+      }
+    }
+  }
+  return true;
+}
+function validateRoleplayTemplatePlugin(plugin) {
+  if (!plugin.metadata) {
+    throw new Error("Plugin metadata is required");
+  }
+  if (!plugin.metadata.templateId || plugin.metadata.templateId.trim() === "") {
+    throw new Error("Plugin metadata.templateId is required");
+  }
+  if (!/^[a-z0-9-]+$/.test(plugin.metadata.templateId)) {
+    throw new Error("Plugin templateId 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.templates || !Array.isArray(plugin.templates) || plugin.templates.length === 0) {
+    throw new Error("Plugin must have at least one template");
+  }
+  for (const template of plugin.templates) {
+    validateTemplateConfig(template);
+  }
+  return true;
+}
+
 // src/index.ts
-var PLUGIN_UTILS_VERSION = "1.1.0";
+var PLUGIN_UTILS_VERSION = "1.2.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   OpenAICompatibleProvider,
@@ -646,6 +788,8 @@ var PLUGIN_UTILS_VERSION = "1.1.0";
   createConsoleLogger,
   createNoopLogger,
   createPluginLogger,
+  createRoleplayTemplatePlugin,
+  createSingleTemplatePlugin,
   detectToolCallFormat,
   getLogLevelFromEnv,
   hasCoreLogger,
@@ -653,6 +797,8 @@ var PLUGIN_UTILS_VERSION = "1.1.0";
   parseAnthropicToolCalls,
   parseGoogleToolCalls,
   parseOpenAIToolCalls,
-  parseToolCalls
+  parseToolCalls,
+  validateRoleplayTemplatePlugin,
+  validateTemplateConfig
 });
 //# sourceMappingURL=index.js.map