1.0.0 • Published 6 months ago

mayu-plugin v1.0.0

Weekly downloads
-
License
ISC
Repository
-
Last release
6 months ago

@mayu/plugin

This package provides the core Plugin class for creating Mayu plugins. The Plugin class helps you structure your plugin code, define input validation using Zod schemas, and manage plugin metadata.

Installation

npm install @mayu/plugin

Usage

import { z } from "zod";
import { Plugin } from "@mayu/plugin";

// Define your plugin's input schema using Zod:
const inputSchema = z
  .object({
    name: z.string().describe("The user's name"),
    age: z.number().min(0).describe("The user's age (must be non-negative)"),
  })
  .describe("Input for the MyGreetingPlugin");

// Create an instance of the Plugin class:
const myPlugin = new Plugin(
  "MyGreetingPlugin", // Plugin name (unique identifier)
  "A simple plugin that greets the user.", // User-friendly description
  "https://example.com/logo.png", // Logo URL (optional). Can also be a local file path.
  false, // isPublished - Set to true when you publish your plugin
  false, // isLocal - Set to true if your plugin runs locally (not in the cloud)
  inputSchema, // The Zod schema for input validation
  ["greeting", "utility"], // Tags to categorize/describe your plugin
  async (input) => {
    // The plugin's core function. Can be async or sync.
    return {
      greeting: `Hello, ${input.name}! You are ${input.age} years old.`,
    };
  }
);

// Example usage (you would typically export a function for Langchain):
export async function runMyPlugin(input: unknown) {
  // Exported function that can be used by LangChain or other tools.
  try {
    const result = await myPlugin.execute(input); // Call myPlugin.execute to validate and execute the plugin logic.
    console.log(result);
    return result;
  } catch (error) {
    // Handle validation or other errors.
    console.error("Plugin execution failed:", error);
    throw error; // Or handle the error as needed.
  }
}

// Example input:
const testInput = { name: "Alice", age: 30 };
runMyPlugin(testInput);

Plugin Class Properties

  • name: (string) - The name of your plugin. This should be a unique identifier.
  • description: (string) - A user-friendly description of your plugin's functionality.
  • logo: (string | null) - A URL or local file path to your plugin's logo. This is optional. If provided, the Plugin class will perform basic validation to check if the path exists or if the URL is valid.
  • isPublished: (boolean) - Set to true when you publish your plugin. This helps track the plugin's status.
  • isLocal: (boolean) - Set to true if your plugin runs locally (not in the cloud).
  • inputSchema: (ZodSchema) - A Zod schema that defines and validates the input to your plugin. This is very important for ensuring data integrity. See the Zod documentation for how to create schemas.
  • tags: (string[]) - An array of strings that categorize or describe your plugin (e.g., "image editing", "productivity").
  • function: ((input: validatedInputType) => Promise | any) - Your plugin's core executable function. This function receives the validated input (based on your inputSchema) and should return the plugin's output. It can be either a synchronous or asynchronous function.

Plugin Class Methods

  • validateInput(input: unknown): Validates the provided input against the plugin's inputSchema. Returns the validated input if successful, or throws a ZodError if validation fails.
  • execute(input: unknown): Executes the plugin's core function (this.function) with the provided input. It first validates the input using validateInput(). Returns a Promise that resolves to the result of the plugin's execution.

Example using Synchronous Function

import { z } from "zod";
import { Plugin } from "@mayu/plugin";

const inputSchema = z.object({
  message: z.string(),
});

const mySyncPlugin = new Plugin(
  "MySyncPlugin",
  "A synchronous plugin example",
  null,
  false,
  true,
  inputSchema,
  [], // Tags
  (input) => {
    console.log("Input message:", input.message);
    return `Processed: ${input.message}`;
  }
);

export function runMySyncPlugin(input: any) {
  // Synchronous version of the exported function
  return mySyncPlugin.execute(input);
}

Important Notes

  • Input Validation: Using Zod schemas for input validation is strongly recommended. It ensures data integrity and helps catch errors early.
  • Error Handling: Make sure to handle potential errors during plugin execution (e.g., network errors, API errors) within your plugin's core function. The execute() method handles ZodError for input validation, but you need to handle other errors yourself.
  • Asynchronous Operations: If your plugin performs asynchronous operations (e.g., network requests), make your core function (this.function) an async function and return a Promise.

License

ISC

1.0.0

6 months ago