@firefliesai/schema-forge
Version:
Transform TypeScript classes into JSON Schema definitions with automatic support for OpenAI, Anthropic, and Google Gemini function calling (tool) formats
399 lines (398 loc) • 13.5 kB
TypeScript
import { AnthropicToolFunction, AnthropicToolOptions, GeminiOldResponseSchema, GeminiOldToolFunction, GeminiResponseSchema, GeminiResponseSchemaOptions, GeminiToolFunction, GeminiToolOptions, GeminiVertexResponseSchema, GeminiVertexToolFunction, JSONSchemaDefinition, OpenAIResponseApiTextSchema, OpenAIResponseApiToolFunction, OpenAIResponseFormatJsonSchema, OpenAIResponseFormatOptions, OpenAIToolFunction, OpenAIToolOptions } from './types';
/**
* Converts a JSON Schema to OpenAI tool format for Chat Completions API
*
* @example
* // Convert a JSON schema to OpenAI tool format
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const tool = jsonSchemaToOpenAITool(
* schema,
* { name: 'create_user', description: 'Creates a new user' },
* { strict: true }
* );
*/
export declare function jsonSchemaToOpenAITool(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}, options?: {
strict?: boolean;
}): OpenAIToolFunction;
/**
* Converts a JSON Schema to OpenAI tool format for Response API
*
* @example
* // Convert a JSON schema to OpenAI Response API tool format
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const tool = jsonSchemaToOpenAIResponseApiTool(
* schema,
* { name: 'create_user', description: 'Creates a new user' },
* { strict: true }
* );
*/
export declare function jsonSchemaToOpenAIResponseApiTool(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}, options: {
strict: boolean;
}): OpenAIResponseApiToolFunction;
/**
* Converts a JSON Schema to OpenAI response format for Chat Completions API
*
* @example
* // Convert a JSON schema to OpenAI response format
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const format = jsonSchemaToOpenAIResponseFormat(
* schema,
* { name: 'user_profile', description: 'User profile information' },
* { strict: true }
* );
*/
export declare function jsonSchemaToOpenAIResponseFormat(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}, options?: {
strict?: boolean;
}): OpenAIResponseFormatJsonSchema;
/**
* Converts a JSON Schema to OpenAI text format for Response API
*
* @example
* // Convert a JSON schema to OpenAI Response API text format
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const format = jsonSchemaToOpenAIResponseApiTextSchema(
* schema,
* { name: 'user_profile', description: 'User profile information' },
* { strict: true }
* );
*/
export declare function jsonSchemaToOpenAIResponseApiTextSchema(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}, options?: {
strict?: boolean;
}): OpenAIResponseApiTextSchema;
/**
* Converts a JSON Schema to Anthropic tool format
*
* @example
* // Convert a JSON schema to Anthropic tool format
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const tool = jsonSchemaToAnthropicTool(
* schema,
* { name: 'create_user', description: 'Creates a new user' }
* );
*/
export declare function jsonSchemaToAnthropicTool(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}): AnthropicToolFunction;
/**
* Converts a JSON Schema to Gemini tool format (@google/genai)
*
* @example
* // Convert a JSON schema to Gemini tool format
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const tool = jsonSchemaToGeminiTool(
* schema,
* { name: 'create_user', description: 'Creates a new user' }
* );
*/
export declare function jsonSchemaToGeminiTool(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}): GeminiToolFunction;
/** @google/generative-ai */
export declare function jsonSchemaToGeminiOldTool(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}): GeminiOldToolFunction;
/** @google-cloud/vertexai */
export declare function jsonSchemaToGeminiVertexTool(schema: JSONSchemaDefinition, metadata: {
name: string;
description?: string;
}): GeminiVertexToolFunction;
/**
* Converts a JSON Schema to Gemini response schema format (@google/genai)
*
* @example
* // Convert a JSON schema to Gemini response schema
* const schema = {
* type: 'object',
* properties: { name: { type: 'string' } },
* required: ['name']
* };
*
* const responseSchema = jsonSchemaToGeminiResponseSchema(
* schema,
* { description: 'User profile information' }
* );
*/
export declare function jsonSchemaToGeminiResponseSchema(schema: JSONSchemaDefinition, metadata: {
description?: string;
}): GeminiResponseSchema;
/** @google/generative-ai */
export declare function jsonSchemaToGeminiOldResponseSchema(schema: JSONSchemaDefinition, metadata: {
description?: string;
}): GeminiOldResponseSchema;
export declare function jsonSchemaToGeminiVertexResponseSchema(schema: JSONSchemaDefinition, metadata: {
description?: string;
}): GeminiVertexResponseSchema;
/**
* Creates an OpenAI-compatible tool function from a class
*
* @example
* // Using options object
* const tool = classToOpenAITool(UserClass, {
* forStructuredOutput: true,
* propertyOverrides: {
* 'username': { description: 'Override description' }
* }
* });
*
* // Use with OpenAI API:
* const response = await openai.chat.completions.create({
* model: "gpt-4o-mini",
* messages: [...],
* tools: [tool]
* });
*/
export declare function classToOpenAITool<T extends object>(target: new (...args: any[]) => T, options?: OpenAIToolOptions<T>): OpenAIToolFunction;
/**
* Creates an OpenAI-compatible tool function for the Response API from a class
*
* Note: This is for use with OpenAI's newer Response API, which has a slightly
* different format than the Chat Completions API.
*
* @example
* // Create a tool for OpenAI Response API
* const tool = classToOpenAIResponseApiTool(UserClass, {
* forStructuredOutput: true,
* });
*
* // Use with OpenAI Response API:
* const response = await openai.responses.create({
* model: "gpt-4o-mini",
* input: "Create a user with name John Doe",
* tools: [tool]
* });
*/
export declare function classToOpenAIResponseApiTool<T extends object>(target: new (...args: any[]) => T, options?: OpenAIToolOptions<T>): OpenAIResponseApiToolFunction;
/**
* Creates an OpenAI response_format compatible JSON schema from a class.
* Can be used for both normal and structured outputs with OpenAI chat completions.
*
* @example
* // For structured output (common case):
* const responseFormat = classToOpenAIResponseFormatJsonSchema(UserClass, {
* forStructuredOutput: true,
* });
*
* // Use with OpenAI API:
* const completion = await openai.chat.completions.create({
* model: "gpt-4o-mini",
* messages: [...],
* response_format: responseFormat,
* });
*/
export declare function classToOpenAIResponseFormatJsonSchema<T extends object>(target: new (...args: any[]) => T, options?: OpenAIResponseFormatOptions<T>): OpenAIResponseFormatJsonSchema;
/**
* Creates a JSON schema for structured output with OpenAI's Response API
*
* This function is specifically designed for OpenAI's new Response API, which has
* a slightly different format for JSON schema structured output compared to
* the Chat Completions API.
*
* @example
* // Create a response format for OpenAI Response API
* const responseFormat = classToOpenAIResponseApiTextSchema (UserOutput, {
* forStructuredOutput: true
* });
*
* // Use with OpenAI Response API:
* const result = await openai.responses.create({
* model: "gpt-4o-mini",
* input: "Give me user information for John Doe",
* text: {
* format: responseFormat
* }
* });
*
* // Parse the response
* const data = JSON.parse(result.output[0].content[0].text);
*/
export declare function classToOpenAIResponseApiTextSchema<T extends object>(target: new (...args: any[]) => T, options?: OpenAIResponseFormatOptions<T>): OpenAIResponseApiTextSchema;
/**
* Creates a Gemini-compatible tool function from a class
*
* @example
* const toolDeclaration = classToGeminiTool(UserClass, {
* propertyOverrides: {
* 'username': { description: 'Custom description' }
* }
* });
*
* // Use with Google @google/genai:
* const model = genAI.getGenerativeModel({
* model: "gemini-2.0-flash-001",
* tools: { functionDeclarations: [toolDeclaration] },
* });
*/
export declare function classToGeminiTool<T extends object>(target: new (...args: any[]) => T, options?: GeminiToolOptions<T>): GeminiToolFunction;
/** @google/generative-ai */
export declare function classToGeminiOldTool<T extends object>(target: new (...args: any[]) => T, options?: GeminiToolOptions<T>): GeminiOldToolFunction;
export declare function classToGeminiVertexTool<T extends object>(target: new (...args: any[]) => T, options?: GeminiToolOptions<T>): GeminiVertexToolFunction;
/**
* Creates an Anthropic-compatible tool function from a class
*
* @example
* const tool = classToAnthropicTool(UserClass, {
* propertyOverrides: {
* 'username': { description: 'Custom description' }
* }
* });
*
* // Use with Anthropic API:
* const message = await anthropic.messages.create({
* model: "claude-3-7-sonnet-20250219",
* max_tokens: 1000,
* messages: [...],
* tools: [tool],
* });
*/
export declare function classToAnthropicTool<T extends object>(target: new (...args: any[]) => T, options?: AnthropicToolOptions<T>): AnthropicToolFunction;
/**
* Creates a Gemini response schema for structured output
*
* Note: Gemini's structured output supports top-level arrays unlike OpenAI.
* This function always generates an object-type schema (from a class),
* but Gemini also supports array schemas like:
* ```
* {
* type: "ARRAY",
* items: {
* type: "OBJECT",
* properties: {...}
* }
* }
* ```
* If you need an array schema, you would need to manually wrap the result
* or create a dedicated helper function.
*
* @example
* const responseSchema = classToGeminiResponseSchema(RecipeClass, {
* propertyOverrides: {
* 'ingredients': { description: 'List of recipe ingredients' }
* }
* });
*
* // Use with Google @google/genai:
* const response = await gemini.models.generateContent({
* model: 'gemini-2.0-flash-001',
* contents: userMessage,
* config: {
* responseMimeType: 'application/json',
* responseSchema: responseSchema,
* },
* });
*/
export declare function classToGeminiResponseSchema<T extends object>(target: new (...args: any[]) => T, options?: GeminiResponseSchemaOptions<T>): GeminiResponseSchema;
export declare function classToGeminiOldResponseSchema<T extends object>(target: new (...args: any[]) => T, options?: GeminiResponseSchemaOptions<T>): GeminiOldResponseSchema;
/** @google-cloud/vertexai */
export declare function classToGeminiVertexResponseSchema<T extends object>(target: new (...args: any[]) => T, options?: GeminiResponseSchemaOptions<T>): GeminiVertexResponseSchema;
/**
* Extracts JSON Schema and metadata from an OpenAI Chat Completions API tool format
*
* This function is useful when you want to convert an existing OpenAI tool definition
* to another LLM format (e.g., Anthropic or Gemini) or when you need to extract
* the JSON Schema for other purposes.
*
* @example
* // Extract JSON Schema from an OpenAI tool
* const openaiTool = {
* type: 'function',
* function: {
* name: 'get_user',
* description: 'Get user information',
* parameters: {
* type: 'object',
* properties: { id: { type: 'string' } },
* required: ['id']
* }
* }
* };
*
* const { schema, metadata } = openAIToolToJsonSchema(openaiTool);
*
* // Convert to Anthropic format
* const anthropicTool = jsonSchemaToAnthropicTool(schema, metadata);
*/
export declare function openAIToolToJsonSchema(openAITool: OpenAIToolFunction): {
schema: JSONSchemaDefinition;
metadata: {
name: string;
description?: string;
};
};
/**
* Extracts JSON Schema and metadata from an OpenAI Response API tool format
*
* This function is useful when you want to convert an existing OpenAI Response API tool
* definition to another LLM format (e.g., Anthropic or Gemini) or when you need to extract
* the JSON Schema for other purposes.
*
* @example
* // Extract JSON Schema from an OpenAI Response API tool
* const responseApiTool = {
* type: 'function',
* name: 'get_user',
* description: 'Get user information',
* parameters: {
* type: 'object',
* properties: { id: { type: 'string' } },
* required: ['id']
* },
* strict: true
* };
*
* const { schema, metadata } = openAIResponseApiToolToJsonSchema(responseApiTool);
*
* // Convert to Gemini format
* const geminiTool = jsonSchemaToGeminiTool(schema, metadata);
*/
export declare function openAIResponseApiToolToJsonSchema(openAITool: OpenAIResponseApiToolFunction): {
schema: JSONSchemaDefinition;
metadata: {
name: string;
description?: string;
};
};