# @smartytalent/openai-tools

[![npm version](https://img.shields.io/npm/v/@smartytalent/openai-tools.svg)](https://www.npmjs.com/package/@smartytalent/openai-tools)
[![npm downloads](https://img.shields.io/npm/dm/@smartytalent/openai-tools.svg)](https://www.npmjs.com/package/@smartytalent/openai-tools)

OpenAI **function / tool calling** definitions for the **SmartyTalent** recruitment API.

This package ships a pre-built `tools.json` generated from the SmartyTalent OpenAPI spec — one tool per API operation — ready to drop into the `tools` parameter of the OpenAI Chat Completions or Responses API.

## Install

```bash
npm install @smartytalent/openai-tools
```

## What's inside

An array of tool definitions in OpenAI's `{ type: "function", function: {...} }` format:

```ts
interface OpenAITool {
  type: 'function'
  function: {
    name: string                                    // snake_case, e.g. "list_tenants"
    description: string                             // from OpenAPI summary/description
    parameters: Record<string, unknown>             // JSON Schema
  }
}
```

## Quick start

```ts
import OpenAI from 'openai'
import { tools } from '@smartytalent/openai-tools'

const openai = new OpenAI()

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'List all active tenants' }],
  tools,
})

const toolCall = response.choices[0].message.tool_calls?.[0]
if (toolCall) {
  const args = JSON.parse(toolCall.function.arguments)
  const result = await executeSmartyTalentTool(toolCall.function.name, args)
  // feed result back into the conversation...
}
```

## Executing tool calls

This package **only defines the tool schemas** — it doesn't ship an executor. Pair it with [`@smartytalent/api-client`](https://www.npmjs.com/package/@smartytalent/api-client) to dispatch tool calls against the live API:

```ts
import { Configuration, TenantsApi } from '@smartytalent/api-client'

const config = new Configuration({ basePath: '...', apiKey: `Bearer ${token}` })

async function executeSmartyTalentTool(name: string, args: Record<string, unknown>) {
  switch (name) {
    case 'list_tenants':
      return new TenantsApi(config).listTenants(args)
    // ... map other tool names to their API methods
  }
}
```

A generic dispatcher can be built by parsing the tool name back to an operationId and routing through the appropriate API class.

## Filtering the tool catalog

The API exposes a lot of operations — feeding all of them to a model wastes context. Filter to the ones relevant for your use case:

```ts
import { tools } from '@smartytalent/openai-tools'

const candidateTools = tools.filter((t) =>
  t.function.name.includes('candidate') || t.function.name.includes('job'),
)
```

## Raw JSON

```ts
import tools from '@smartytalent/openai-tools/dist/tools.json'
```

## Versioning

Published in lockstep with `@smartytalent/api-client`. Pin both packages to the same version.

## License

Licensed under the [Apache License, Version 2.0](./LICENSE).

Copyright © 2026 SmartyTalent (SmartyMeet sp. z o.o.)