@reaatech/structured-function-calling-ai-core

Zod-based tool definitions, registry, and provider-agnostic JSON Schema generation.

Installation

terminal

pnpm add @reaatech/structured-function-calling-ai-core

API

`ToolDefinition<I>`

typescript

type ToolDefinition<I = unknown> = {
  readonly name: string;
  readonly description: string;
  readonly schema: z.ZodSchema<I>;
  readonly execute: (input: I) => Promise<unknown>;
};

The canonical shape for a callable tool. The generic I types the input validated by schema before execute is called.

`ToolRegistry`

typescript

class ToolRegistry {
  register(defn: ToolDefinition): void;
  get(name: string): ToolDefinition;
  list(): ToolDefinition[];
  has(name: string): boolean;
  remove(name: string): void;
}

In-memory store for tool definitions. register throws DuplicateToolError if a tool with the same name already exists. get throws ToolNotFoundError if the tool is not found.

`convertToJsonSchema`

typescript

function convertToJsonSchema(
  schema: z.ZodSchema<unknown>,
  name?: string,
  options?: {
    target?: 'jsonSchema7' | 'openAi';
    rejectedAdditionalProperties?: false;
  },
): JsonSchema7Type

Wraps zod-to-json-schema with target: 'openAi' as the default. Use target: 'jsonSchema7' for the full JSON Schema draft-07 output. Pass rejectedAdditionalProperties: false to suppress the additionalProperties keyword in the output schema.

`ToolNotFoundError`

typescript

class ToolNotFoundError extends Error {
  readonly name: string;
  constructor(name: string);
}

`DuplicateToolError`

typescript

class DuplicateToolError extends Error {
  readonly name: string;
  constructor(name: string);
}

Usage example

typescript

import { z } from 'zod/v3';
import { ToolRegistry, convertToJsonSchema } from '@reaatech/structured-function-calling-ai-core';
 
const schema = z.object({ city: z.string(), units: z.enum(['metric', 'imperial']) });
 
const registry = new ToolRegistry();
registry.register({
  name: 'get_weather',
  description: 'Get weather for a city',
  schema,
  execute: async (input) => {
    // input is typed as { city: string; units: 'metric' | 'imperial' }
    return { temp: 22, conditions: 'sunny' };
  },
});
 
const jsonSchema = convertToJsonSchema(schema, 'GetWeather', { target: 'openAi' });
// → JSON Schema compatible with OpenAI's function-calling format

Dependencies

zod 4.4.3
zod-to-json-schema 3.25.2