Class Shuriken

Example: Basic Shuriken Creation

const weatherShuriken = new Shuriken(
  'get_weather',
  'Get current weather information for a specific city',
  z.object({
    city: z.string().describe('The city name'),
    unit: z.enum(['celsius', 'fahrenheit']).optional()
  }),
  async (params) => {
    // Implementation logic here
    return { temperature: 25, condition: 'Sunny' };
  }
);

Example: Using a Shuriken

// Execute the shuriken
const result = await weatherShuriken.execute({ 
  city: 'Paris', 
  unit: 'celsius' 
});

// Validate parameters
const validation = weatherShuriken.validate({ city: 'London' });
if (validation.success) {
  console.log('Valid parameters:', validation.data);
}

// Generate OpenAI tool definition
const toolDef = weatherShuriken.forge();

Since

1.0.0

Constructors

constructor

Methods

forge validate execute getId getName getDescription getImplementation getSchema

Constructors

constructor

  • new Shuriken(title, description, schema, implementation): Shuriken

  • Creates an instance of Shuriken.

    Parameters

    • title: string

      The name of the shuriken, used as the function name in OpenAI tool calls. Must contain only alphanumeric characters, underscores, and hyphens.

    • description: string

      A brief description of what the shuriken does. This helps the AI decide when to use it.

    • schema: ZodType<any, ZodTypeDef, any>

      A Zod schema defining the expected parameters for the shuriken's implementation.

    • implementation: Function

      The actual JavaScript/TypeScript function that performs the shuriken's logic.

    Returns Shuriken

    Example: Creating a Calculator Shuriken

    const calculator = new Shuriken(
      'calculate',
      'Perform basic mathematical operations',
      z.object({
        operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
        a: z.number(),
        b: z.number()
      }),
      (params) => {
        switch (params.operation) {
          case 'add': return params.a + params.b;
          case 'subtract': return params.a - params.b;
          case 'multiply': return params.a * params.b;
          case 'divide': return params.a / params.b;
        }
      }
    );

    Since

    1.0.0

Methods

forge

  • forge(): ChatCompletionTool

  • Generates the OpenAI tool definition for this shuriken. This definition is used by OpenAI models to understand and call the shuriken.

    Returns ChatCompletionTool

    An OpenAI ChatCompletionTool object that can be used in API calls.

    Example: Generating Tool Definition

    const weatherShuriken = new Shuriken(
      'get_weather',
      'Get current weather information',
      z.object({ city: z.string() }),
      async (params) => ({ temperature: 25, condition: 'Sunny' })
    );

    const toolDefinition = weatherShuriken.forge();
    // toolDefinition will be:
    // {
    //   type: 'function',
    //   function: {
    //     name: 'get_weather',
    //     description: 'Get current weather information',
    //     parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] }
    //   }
    // }

    Since

    1.0.0

validate

  • validate(parameters): {
        success: boolean;
        data?: any;
        error?: string;
    }

  • Validates the given parameters against the shuriken's defined Zod schema.

    Parameters

    • parameters: any

      The parameters to validate.

    Returns {
        success: boolean;
        data?: any;
        error?: string;
    }

    An object indicating success or failure, with data or error details.

    • success: boolean
    • Optional data?: any
    • Optional error?: string

    Example: Parameter Validation

    const validation = shuriken.validate({ city: 'Paris' });
    if (validation.success) {
      console.log('Valid parameters:', validation.data);
    } else {
      console.error('Validation error:', validation.error);
    }

    Since

    1.0.0

execute

  • execute(parameters): Promise<ExecutionResult<any>>

  • Executes the shuriken's underlying implementation function with the provided parameters. Parameters are validated against the schema before execution.

    Parameters

    • parameters: any

      The parameters to pass to the shuriken's implementation.

    Returns Promise<ExecutionResult<any>>

    A promise that resolves to an ExecutionResult containing the result and execution time.

    Throws

    If parameter validation fails or if the shuriken's implementation throws an error.

    Example: Executing a Shuriken

    const calculator = new Shuriken(
      'add',
      'Adds two numbers',
      z.object({ a: z.number(), b: z.number() }),
      (params) => params.a + params.b
    );

    try {
      const result = await calculator.execute({ a: 5, b: 3 });
      console.log('Result:', result.result); // 8
      console.log('Execution time:', result.executionTime); // e.g., 2
    } catch (error) {
      console.error('Execution failed:', error.message);
    }

    Since

    1.0.0

getId

getName

getDescription

getImplementation

getSchema

  • getSchema(): ZodType<any, ZodTypeDef, any>

  • Gets the Zod schema used for validating the shuriken's parameters.

    Returns ZodType<any, ZodTypeDef, any>

    The shuriken's Zod schema.

    Since

    1.0.0

Settings

Member Visibility

Theme

On This Page

constructorforgevalidateexecutegetIdgetNamegetDescriptiongetImplementationgetSchema