1.0.0 • Published 6 months ago
mayu-plugin v1.0.0
@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, thePlugin
class will perform basic validation to check if the path exists or if the URL is valid.isPublished
: (boolean) - Set totrue
when you publish your plugin. This helps track the plugin's status.isLocal
: (boolean) - Set totrue
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 yourinputSchema
) 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'sinputSchema
. Returns the validated input if successful, or throws aZodError
if validation fails.execute(input: unknown)
: Executes the plugin's core function (this.function
) with the provided input. It first validates the input usingvalidateInput()
. 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 handlesZodError
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
) anasync
function and return aPromise
.
License
ISC
1.0.0
6 months ago