Tools Schema Generator

Tools Schema Generator is a utility for generating JSON schemas from JSDoc comments to streamline the integration of tools with OpenAI's function calling.

This package helps developers create well-structured schemas to define tool behavior, making it easier to build AI agents with dynamic capabilities.

Features

• OpenAI Function Calling Support: Automatically generates JSON schemas compatible with OpenAI's function calling feature.
• Streamlined Agent Creation: Simplifies the process of defining tools for AI agents.
• JSDoc Parsing: Parses JSDoc comments from TypeScript and JavaScript files.
• Complex Schema Support: Handles unions, enums, nested objects, and optional parameters.
• Validation: Ensures schema types are valid and adheres to JSON schema standards.

Installation

1. Clone the repository:

git clone https://github.com/your-username/tools_schema_generator.git
cd tools_schema_generator

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Run the Schema Generator:

npm start

The tool will:

• Parse .ts and .js files in the services directory.
• Generate JSON schemas for tools.
• Save the output to schemas.json.

Usage

For TypeScript Files

To generate schemas from TypeScript files, ensure your files are structured with JSDoc comments. Here's an example:

interface User {
  name: string;
  age: number;
  address?: Address;
}

interface Address {
  street: string;
  city?: string | number;
  country?: string;
}

/**
 * @description Fetch the token balance for a user based on their username and token details.
 * @param user The user object.
 * @param token The token ID to search for.
 */
export async function getUserTokenBalance({
  user,
  token,
}: {
  user: User;
  token: number;
}): Promise<void> {}

Run the schema generator:

npm start

This will scan your TypeScript files (.ts) in the services directory, parse the JSDoc comments, and generate corresponding JSON schemas.

For JavaScript Files

Similarly, for JavaScript files, ensure JSDoc comments are used:

/**
 * @description This function handles a user object
 * @param {object} user The user object
 * @property {string} user.name The user’s name
 * @property {number} [user.age] The user’s age
 * @param {number} token - The token ID to search for.
 */
function getUserTokenBalance({ user, token }) {}

Run the schema generator:

npm start

This will scan your JavaScript files (.js) in the services directory, parse the JSDoc comments, and generate JSON schemas.

Note: Since JavaScript is not a typed language, JSDoc comments for JS files need to be more detailed, and types must be explicitly provided where possible to ensure accurate schema generation.

General Instructions

• Output: After running the command, the generated schemas will be saved in schemas.json at the root of your project.
• Validation: The tool will validate the schemas to ensure they conform to JSON Schema standards. Errors in JSDoc comments (like invalid types) will be reported.

Integrate with OpenAI:

Use the generated schemas to define tools for OpenAI's function calling:

const { Configuration, OpenAIApi } = require("openai");

const configuration = new Configuration({
  apiKey: process.env.OPENAI_API_KEY,
});

const openai = new OpenAIApi(configuration);

const toolsSchema = require("./schemas.json");

const response = await openai.createChatCompletion({
  model: "gpt-4-0613",
  messages: [{ role: "user", content: "What's my account balance?" }],
  tools: toolsSchema,
});

console.log(response.data);

• This setup allows your AI agents or applications to understand and use the functions defined in your code without the need to manually create the files.

Output Example

Example schema for a tool:

[
  {
    "type": "function",
    "function": {
      "name": "getUserTokenBalance",
      "description": "This function handles a user object",
      "parameters": {
        "type": "object",
        "properties": {
          "user": {
            "type": "object",
            "description": "The user object",
            "properties": {
              "name": {
                "type": "string",
                "description": "The user’s name"
              },
              "age": {
                "type": "number",
                "description": "The user’s age"
              }
            },
            "required": ["name"]
          },
          "token": {
            "type": "number",
            "description": "The token ID to search for."
          }
        },
        "required": ["user", "token"]
      }
    }
  }
]

Configuration

Directory Structure:

• Input: By default, the tool scans the services directory for .ts and .js files.

• Output: Schemas are saved to schemas.json in the root directory.

Error Handling:

Invalid types in JSDoc comments throw detailed errors:

Error: Invalid type: obj. Valid types are: string, number, integer, boolean, object, array, null.

Development

File Structure

.
├── dist/               # Compiled JavaScript files
├── src/                # Source files
│   ├── parser/         # Parsing logic
│   │   ├── parseJs.ts  # JSDoc parser for JavaScript
│   │   ├── parseTs.ts  # JSDoc parser for TypeScript
│   └── index.ts        # Entry point for parsing
├── services/           # Example files to parse
├── schemas.json        # Generated schema output
├── types/              # Shared types and interfaces
├── package.json        # Node.js dependencies
└── tsconfig.json       # TypeScript configuration

Scripts

• Build: Compiles TypeScript to JavaScript.

npm run build

• Start: Runs the schema generator.

npm start

Contributing

Contributions are welcome! If you want to report bugs or suggest improvements, feel free to open an issue.

License

This project is licensed under the MIT License.