@quilltap/plugin-utils 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to @quilltap/plugin-utils will be documented in this file.
+
+## [1.0.0] - 2025-12-30
+
+### Added
+
+- Initial release of @quilltap/plugin-utils
+- **Tool Parsing Utilities**
+  - `parseToolCalls()` - Parse tool calls with auto-detection or explicit format
+  - `parseOpenAIToolCalls()` - Parse OpenAI/Grok format tool calls
+  - `parseAnthropicToolCalls()` - Parse Anthropic format tool calls
+  - `parseGoogleToolCalls()` - Parse Google Gemini format tool calls
+  - `detectToolCallFormat()` - Detect the format of a response
+  - `hasToolCalls()` - Quick check if a response contains tool calls
+
+- **Tool Conversion Utilities**
+  - `convertToAnthropicFormat()` - Convert universal tool to Anthropic format
+  - `convertToGoogleFormat()` - Convert universal tool to Google format
+  - `convertFromAnthropicFormat()` - Convert Anthropic tool to universal format
+  - `convertFromGoogleFormat()` - Convert Google tool to universal format
+  - `convertToolTo()` - Convert a tool to any supported format
+  - `convertToolsTo()` - Convert multiple tools to any format
+  - `applyDescriptionLimit()` - Truncate tool description if too long
+
+- **Logger Bridge**
+  - `createPluginLogger()` - Create a logger that bridges to Quilltap core
+  - `hasCoreLogger()` - Check if running inside Quilltap
+  - `getLogLevelFromEnv()` - Get log level from environment variables
+  - Support for child loggers with context inheritance
+  - Automatic fallback to console logging when running standalone

package/README.md

@@ -0,0 +1,167 @@
+# @quilltap/plugin-utils
+
+Utility functions for Quilltap plugin development. This package provides runtime utilities that complement the type definitions in `@quilltap/plugin-types`.
+
+## Installation
+
+```bash
+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[]`:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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 |
+
+## Example: Complete Plugin Provider
+
+```typescript
+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

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+export { AnthropicToolDefinition, GoogleToolDefinition, LogContext, LogLevel, OpenAIToolDefinition, PluginLogger, ToolCall, ToolCallRequest, ToolFormatOptions, ToolResult, UniversalTool, createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';
+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';
+
+/**
+ * @quilltap/plugin-utils
+ *
+ * Utility functions for Quilltap plugin development.
+ *
+ * This package provides runtime utilities that complement the type definitions
+ * in @quilltap/plugin-types. It includes:
+ *
+ * - **Tool Parsing**: Parse tool calls from any LLM provider's response format
+ * - **Tool Conversion**: Convert between OpenAI, Anthropic, and Google tool formats
+ * - **Logger Bridge**: Logging that integrates with Quilltap's core or runs standalone
+ *
+ * @packageDocumentation
+ * @module @quilltap/plugin-utils
+ */
+
+/**
+ * Version of the plugin-utils package.
+ * Can be used at runtime to check compatibility.
+ */
+declare const PLUGIN_UTILS_VERSION = "1.0.0";
+
+export { PLUGIN_UTILS_VERSION };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export { AnthropicToolDefinition, GoogleToolDefinition, LogContext, LogLevel, OpenAIToolDefinition, PluginLogger, ToolCall, ToolCallRequest, ToolFormatOptions, ToolResult, UniversalTool, createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';
+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';
+
+/**
+ * @quilltap/plugin-utils
+ *
+ * Utility functions for Quilltap plugin development.
+ *
+ * This package provides runtime utilities that complement the type definitions
+ * in @quilltap/plugin-types. It includes:
+ *
+ * - **Tool Parsing**: Parse tool calls from any LLM provider's response format
+ * - **Tool Conversion**: Convert between OpenAI, Anthropic, and Google tool formats
+ * - **Logger Bridge**: Logging that integrates with Quilltap's core or runs standalone
+ *
+ * @packageDocumentation
+ * @module @quilltap/plugin-utils
+ */
+
+/**
+ * Version of the plugin-utils package.
+ * Can be used at runtime to check compatibility.
+ */
+declare const PLUGIN_UTILS_VERSION = "1.0.0";
+
+export { PLUGIN_UTILS_VERSION };

package/dist/index.js

@@ -0,0 +1,360 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  PLUGIN_UTILS_VERSION: () => PLUGIN_UTILS_VERSION,
+  __clearCoreLoggerFactory: () => __clearCoreLoggerFactory,
+  __injectCoreLoggerFactory: () => __injectCoreLoggerFactory,
+  applyDescriptionLimit: () => applyDescriptionLimit,
+  convertFromAnthropicFormat: () => convertFromAnthropicFormat,
+  convertFromGoogleFormat: () => convertFromGoogleFormat,
+  convertToAnthropicFormat: () => convertToAnthropicFormat,
+  convertToGoogleFormat: () => convertToGoogleFormat,
+  convertToolTo: () => convertToolTo,
+  convertToolsTo: () => convertToolsTo,
+  createConsoleLogger: () => import_plugin_types.createConsoleLogger,
+  createNoopLogger: () => import_plugin_types.createNoopLogger,
+  createPluginLogger: () => createPluginLogger,
+  detectToolCallFormat: () => detectToolCallFormat,
+  getLogLevelFromEnv: () => getLogLevelFromEnv,
+  hasCoreLogger: () => hasCoreLogger,
+  hasToolCalls: () => hasToolCalls,
+  parseAnthropicToolCalls: () => parseAnthropicToolCalls,
+  parseGoogleToolCalls: () => parseGoogleToolCalls,
+  parseOpenAIToolCalls: () => parseOpenAIToolCalls,
+  parseToolCalls: () => parseToolCalls
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/tools/parsers.ts
+function parseOpenAIToolCalls(response) {
+  const toolCalls = [];
+  try {
+    const resp = response;
+    let toolCallsArray = resp?.tool_calls;
+    if (!toolCallsArray) {
+      const choices = resp?.choices;
+      toolCallsArray = choices?.[0]?.message?.tool_calls;
+    }
+    if (toolCallsArray && Array.isArray(toolCallsArray) && toolCallsArray.length > 0) {
+      for (const toolCall of toolCallsArray) {
+        const tc = toolCall;
+        if (tc.type === "function" && tc.function) {
+          toolCalls.push({
+            name: tc.function.name,
+            arguments: JSON.parse(tc.function.arguments || "{}")
+          });
+        }
+      }
+    }
+  } catch (error) {
+    console.error("[plugin-utils] Error parsing OpenAI tool calls:", error);
+  }
+  return toolCalls;
+}
+function parseAnthropicToolCalls(response) {
+  const toolCalls = [];
+  try {
+    const resp = response;
+    if (!resp?.content || !Array.isArray(resp.content)) {
+      return toolCalls;
+    }
+    for (const block of resp.content) {
+      const b = block;
+      if (b.type === "tool_use" && b.name) {
+        toolCalls.push({
+          name: b.name,
+          arguments: b.input || {}
+        });
+      }
+    }
+  } catch (error) {
+    console.error("[plugin-utils] Error parsing Anthropic tool calls:", error);
+  }
+  return toolCalls;
+}
+function parseGoogleToolCalls(response) {
+  const toolCalls = [];
+  try {
+    const resp = response;
+    const candidates = resp?.candidates;
+    const parts = candidates?.[0]?.content?.parts;
+    if (!parts || !Array.isArray(parts)) {
+      return toolCalls;
+    }
+    for (const part of parts) {
+      const p = part;
+      if (p.functionCall) {
+        toolCalls.push({
+          name: p.functionCall.name,
+          arguments: p.functionCall.args || {}
+        });
+      }
+    }
+  } catch (error) {
+    console.error("[plugin-utils] Error parsing Google tool calls:", error);
+  }
+  return toolCalls;
+}
+function detectToolCallFormat(response) {
+  if (!response || typeof response !== "object") {
+    return null;
+  }
+  const resp = response;
+  if (resp.tool_calls && Array.isArray(resp.tool_calls)) {
+    return "openai";
+  }
+  const choices = resp.choices;
+  if (choices?.[0]?.message?.tool_calls) {
+    return "openai";
+  }
+  if (resp.content && Array.isArray(resp.content)) {
+    const hasToolUse = resp.content.some(
+      (block) => block.type === "tool_use"
+    );
+    if (hasToolUse) {
+      return "anthropic";
+    }
+  }
+  const candidates = resp.candidates;
+  if (candidates?.[0]?.content?.parts) {
+    const hasFunctionCall = candidates[0].content.parts.some((part) => part.functionCall);
+    if (hasFunctionCall) {
+      return "google";
+    }
+  }
+  return null;
+}
+function parseToolCalls(response, format = "auto") {
+  let actualFormat = format;
+  if (format === "auto") {
+    actualFormat = detectToolCallFormat(response);
+    if (!actualFormat) {
+      return [];
+    }
+  }
+  switch (actualFormat) {
+    case "openai":
+      return parseOpenAIToolCalls(response);
+    case "anthropic":
+      return parseAnthropicToolCalls(response);
+    case "google":
+      return parseGoogleToolCalls(response);
+    default:
+      return [];
+  }
+}
+function hasToolCalls(response) {
+  const format = detectToolCallFormat(response);
+  return format !== null;
+}
+
+// src/tools/converters.ts
+function convertToAnthropicFormat(tool) {
+  return {
+    name: tool.function.name,
+    description: tool.function.description,
+    input_schema: {
+      type: "object",
+      properties: tool.function.parameters.properties,
+      required: tool.function.parameters.required
+    }
+  };
+}
+function convertToGoogleFormat(tool) {
+  return {
+    name: tool.function.name,
+    description: tool.function.description,
+    parameters: {
+      type: "object",
+      properties: tool.function.parameters.properties,
+      required: tool.function.parameters.required
+    }
+  };
+}
+function convertFromAnthropicFormat(tool) {
+  return {
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description ?? "",
+      parameters: {
+        type: "object",
+        properties: tool.input_schema.properties,
+        required: tool.input_schema.required ?? []
+      }
+    }
+  };
+}
+function convertFromGoogleFormat(tool) {
+  return {
+    type: "function",
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: {
+        type: "object",
+        properties: tool.parameters.properties,
+        required: tool.parameters.required
+      }
+    }
+  };
+}
+function applyDescriptionLimit(tool, maxBytes) {
+  if (!tool || !tool.description) {
+    return tool;
+  }
+  const warningText = " [Note: description truncated due to length limit]";
+  const maxDescBytes = maxBytes - Buffer.byteLength(warningText);
+  if (maxDescBytes <= 0) {
+    console.warn("[plugin-utils] Length limit too small for warning text:", maxBytes);
+    return tool;
+  }
+  const descBytes = Buffer.byteLength(tool.description);
+  if (descBytes > maxBytes) {
+    let truncated = tool.description;
+    while (Buffer.byteLength(truncated) > maxDescBytes && truncated.length > 0) {
+      truncated = truncated.slice(0, -1);
+    }
+    return {
+      ...tool,
+      description: truncated + warningText
+    };
+  }
+  return tool;
+}
+function convertToolTo(tool, target) {
+  switch (target) {
+    case "anthropic":
+      return convertToAnthropicFormat(tool);
+    case "google":
+      return convertToGoogleFormat(tool);
+    case "openai":
+    default:
+      return tool;
+  }
+}
+function convertToolsTo(tools, target) {
+  return tools.map((tool) => convertToolTo(tool, target));
+}
+
+// src/logging/plugin-logger.ts
+function getCoreLoggerFactory() {
+  return globalThis.__quilltap_logger_factory ?? null;
+}
+function __injectCoreLoggerFactory(factory) {
+  globalThis.__quilltap_logger_factory = factory;
+}
+function __clearCoreLoggerFactory() {
+  globalThis.__quilltap_logger_factory = void 0;
+}
+function hasCoreLogger() {
+  return getCoreLoggerFactory() !== null;
+}
+function createConsoleLoggerWithChild(prefix, minLevel = "debug", baseContext = {}) {
+  const levels = ["debug", "info", "warn", "error"];
+  const shouldLog = (level) => levels.indexOf(level) >= levels.indexOf(minLevel);
+  const formatContext = (context) => {
+    const merged = { ...baseContext, ...context };
+    const entries = Object.entries(merged).filter(([key]) => key !== "context").map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+    return entries ? ` ${entries}` : "";
+  };
+  const logger = {
+    debug: (message, context) => {
+      if (shouldLog("debug")) {
+        console.debug(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    info: (message, context) => {
+      if (shouldLog("info")) {
+        console.info(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    warn: (message, context) => {
+      if (shouldLog("warn")) {
+        console.warn(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    error: (message, context, error) => {
+      if (shouldLog("error")) {
+        console.error(
+          `[${prefix}] ${message}${formatContext(context)}`,
+          error ? `
+${error.stack || error.message}` : ""
+        );
+      }
+    },
+    child: (additionalContext) => {
+      return createConsoleLoggerWithChild(prefix, minLevel, {
+        ...baseContext,
+        ...additionalContext
+      });
+    }
+  };
+  return logger;
+}
+function createPluginLogger(pluginName, minLevel = "debug") {
+  const coreFactory = getCoreLoggerFactory();
+  if (coreFactory) {
+    return coreFactory(pluginName);
+  }
+  return createConsoleLoggerWithChild(pluginName, minLevel);
+}
+function getLogLevelFromEnv() {
+  if (typeof process !== "undefined" && process.env) {
+    const envLevel = process.env.LOG_LEVEL || process.env.QUILTTAP_LOG_LEVEL;
+    if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+      return envLevel;
+    }
+  }
+  return "info";
+}
+
+// src/logging/index.ts
+var import_plugin_types = require("@quilltap/plugin-types");
+
+// src/index.ts
+var PLUGIN_UTILS_VERSION = "1.0.0";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLUGIN_UTILS_VERSION,
+  __clearCoreLoggerFactory,
+  __injectCoreLoggerFactory,
+  applyDescriptionLimit,
+  convertFromAnthropicFormat,
+  convertFromGoogleFormat,
+  convertToAnthropicFormat,
+  convertToGoogleFormat,
+  convertToolTo,
+  convertToolsTo,
+  createConsoleLogger,
+  createNoopLogger,
+  createPluginLogger,
+  detectToolCallFormat,
+  getLogLevelFromEnv,
+  hasCoreLogger,
+  hasToolCalls,
+  parseAnthropicToolCalls,
+  parseGoogleToolCalls,
+  parseOpenAIToolCalls,
+  parseToolCalls
+});
+//# sourceMappingURL=index.js.map