@quilltap/plugin-utils

Utility functions for Quilltap plugin development. This package provides runtime utilities that complement the type definitions in @quilltap/plugin-types.

Installation

npm install @quilltap/plugin-utils @quilltap/plugin-types

Features

Tool Parsing

Parse tool calls from any LLM provider's response format into a standardized ToolCallRequest[]:

import { parseToolCalls, parseOpenAIToolCalls } from '@quilltap/plugin-utils';

// Auto-detect format
const toolCalls = parseToolCalls(response, 'auto');

// Or use provider-specific parsers
const openaiCalls = parseOpenAIToolCalls(response);
const anthropicCalls = parseAnthropicToolCalls(response);
const googleCalls = parseGoogleToolCalls(response);

Tool Format Conversion

Convert between OpenAI, Anthropic, and Google tool formats:

import {
  convertToAnthropicFormat,
  convertToGoogleFormat,
  convertToolsTo
} from '@quilltap/plugin-utils';

// Convert a single tool
const anthropicTool = convertToAnthropicFormat(universalTool);
const googleTool = convertToGoogleFormat(universalTool);

// Convert multiple tools
const anthropicTools = convertToolsTo(tools, 'anthropic');

Logger Bridge

Create a logger that integrates with Quilltap's core logging system when running inside the host application, or falls back to console logging when running standalone:

import { createPluginLogger } from '@quilltap/plugin-utils';

// Create a logger for your plugin
const logger = createPluginLogger('qtap-plugin-my-provider');

// Use it like any standard logger
logger.debug('Initializing provider', { version: '1.0.0' });
logger.info('Provider ready');
logger.warn('Rate limit approaching', { remaining: 10 });
logger.error('API call failed', { endpoint: '/chat' }, error);

// Create child loggers with additional context
const childLogger = logger.child({ component: 'auth' });
childLogger.info('Validating API key');

When running inside Quilltap:

• Logs are routed to Quilltap's core logging system
• Logs appear in logs/combined.log and console
• Each log is tagged with { plugin: 'your-plugin-name', module: 'plugin' }

When running standalone:

• Logs are written to console with [plugin-name] prefix
• Respects LOG_LEVEL or QUILLTAP_LOG_LEVEL environment variables

API Reference

Tool Parsing

| Function | Description | |----------|-------------| | parseToolCalls(response, format) | Parse tool calls with auto-detection or explicit format | | parseOpenAIToolCalls(response) | Parse OpenAI/Grok format tool calls | | parseAnthropicToolCalls(response) | Parse Anthropic format tool calls | | parseGoogleToolCalls(response) | Parse Google Gemini format tool calls | | detectToolCallFormat(response) | Detect the format of a response | | hasToolCalls(response) | Check if a response contains tool calls |

Tool Conversion

| Function | Description | |----------|-------------| | convertToAnthropicFormat(tool) | Convert universal tool to Anthropic format | | convertToGoogleFormat(tool) | Convert universal tool to Google format | | convertFromAnthropicFormat(tool) | Convert Anthropic tool to universal format | | convertFromGoogleFormat(tool) | Convert Google tool to universal format | | convertToolTo(tool, target) | Convert a tool to any supported format | | convertToolsTo(tools, target) | Convert multiple tools to any format | | applyDescriptionLimit(tool, maxBytes) | Truncate tool description if too long |

Logging

| Function | Description | |----------|-------------| | createPluginLogger(name, minLevel?) | Create a plugin logger with core bridge | | hasCoreLogger() | Check if running inside Quilltap | | getLogLevelFromEnv() | Get log level from environment variables | | 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:

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:

npm install openai

System Prompt Plugin Utilities

Create system prompt plugins that provide character prompt templates from .md files:

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

import { createPluginLogger, parseOpenAIToolCalls } from '@quilltap/plugin-utils';
import type { LLMProvider, LLMParams, LLMResponse, ToolCallRequest } from '@quilltap/plugin-types';
import OpenAI from 'openai';

const logger = createPluginLogger('qtap-plugin-my-provider');

export class MyProvider implements LLMProvider {
  private client: OpenAI;

  constructor(apiKey: string) {
    this.client = new OpenAI({ apiKey });
    logger.debug('Provider initialized');
  }

  async sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse> {
    logger.debug('Sending message', { model: params.model, messageCount: params.messages.length });

    try {
      const response = await this.client.chat.completions.create({
        model: params.model,
        messages: params.messages,
        tools: params.tools,
      });

      // Parse tool calls using the utility
      const toolCalls = parseOpenAIToolCalls(response);

      logger.info('Received response', {
        hasToolCalls: toolCalls.length > 0,
        tokens: response.usage?.total_tokens,
      });

      return {
        content: response.choices[0].message.content || '',
        toolCalls,
        usage: {
          promptTokens: response.usage?.prompt_tokens || 0,
          completionTokens: response.usage?.completion_tokens || 0,
          totalTokens: response.usage?.total_tokens || 0,
        },
      };
    } catch (error) {
      logger.error('Failed to send message', { model: params.model }, error as Error);
      throw error;
    }
  }
}

License

MIT - Foundry-9 LLC