@draftor/tools/README.md

A simple TypeScript/Javascript functions to openai tool call format

# @draftor/tools


A simple TypeScript npm package designed to transform your function comments into an OpenAI Tool calling format. It's an alternative to `zod` and `z`. Built to maintain functions used for tool calling in a separate file, this package allows you to generate OpenAI Tool Calling JSON format without writing extensive code or using `.describe()`.
<br>
<br>
#### ⚠️  Caution: Check your Linter and Prettier config before add this package!

This approach deviates from typical TypeScript patterns. The comment must reside **within** the function, not outside. For example:


```
DO ✅ 
export function foo(bar:string) {
  /**
   * @description Converts a number to its string representation.
   * @param {boolean} bar - The bool to convert.
   * @param {number} abc - The number to convert.
   * @param {string} xyz - The string to convert.
   * @param {undefined} mpn - The any to convert.
   * @returns {object} The Object as response.
   */
  return bar.toString();
}

DON'T ❌
/**
 * @description Converts a number to its string representation.
 * @param {boolean} bar - The number to convert.
 * @param {number} abc - The number to convert.
 * @param {string} xyz - The number to convert.
 * @param {undefined} mpn - The number to convert.
 * @returns {object} The string representation of the input number.
 */
export function foo(bar: string) {
  return bar.toString();
}

```


## Installation

To install the package, use npm:

```bash
npm install @draftor/tools
```

## Usage

#### 1. Converting Functions to OpenAI Format

Here's a basic example of how to use the `Tools` class:

Your tool/functions for tool calling

```typescript
# yourFunctions.ts

export function foo(bar:string) {
  /**
   * @description Converts a number to its string representation.
   * @param {boolean} bar - The number to convert.
   * @param {number} abc - The number to convert.
   * @param {string} xyz - The number to convert.
   * @param {undefined} mpn - The number to convert.
   * @returns {object} The string representation of the input number.
   */
  return bar.toString();
}
```

```typescript

import { Tools } from '@draftor/tools';
import { foo } from './yourFunctions';

const tools = new Tools(funcs);
const result = tools.toOpenAI(); // --> for object response
// const result = tools.toOpenAI('string'); -->  for string response

console.log(result); //will print in json string as output

```

```bash
{
  "name": "foo",
  "description": "No description provided.",
  "params": {
    "type": "object",
    "properties": {
      "bar": {
        "type": "boolean",
        "description": "The number to convert."
      },
      "abc": {
        "type": "number",
        "description": "The number to convert."
      },
      "xyz": {
        "type": "string",
        "description": "The number to convert."
      },
      "mpn": {
        "type": "any",
        "description": "The number to convert."
      }
    },
    "required": [
      "bar",
      "abc",
      "xyz",
      "mpn"
    ]
  },
  "returns": {
    "type": "object",
    "description": "The string representation of the input number."
  }
}
```

#### 2. Executing LLM ToolCalls from response

```typescript
// Response Format

export interface IToolCall {
  index: number,
  id: string;
  type: 'function';
  function: IFunctionCall;
}

export interface IFunctionCall {
  name: string;
  arguments: string;
}
```
How to execute the tool calls

```typescript
const response = await LLM.chat({msg, tools}) // mock api. Use an endpoint of your choice

const toolsFromLLM = getToolsFromResponse(response) as IToolCall; // Implement response.data.choices[0].message.content logic with or without stream and extract tools object.

/**
 * You can either use the ToolCall response directly by looping over the tools and executing them.
 * ---===  OR  ===---
 * Implement the logic yourself, convert the tools to functions and arguments, and pass them to this function for execution.
 * However, if you've already implemented this much, it's pretty unnecessary to use the .exec() function!
 */

const funResp = tool.exec(toolsFromLLM); // If there is code in the args response, be sure to have an escape logic, but Ideally shoould work.
 
 OR
const funResp = tool.exec('foo', { bar: 'Waba laba dub dub!' });
```


## Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.


## License

This project is licensed under the [MIT License](LICENSE).


## Author

https://x.com/p_naix

Built with ❤️ by Team [Draftor.ai](https://draftor.ai)

Twitter : https://twitter.com/draftor_ai

## Acknowledgments

- [doctrine](https://github.com/eslint/doctrine) for JSDoc parsing.