# @isdk/ai-tool

> AI tools

Latest version **0.9.0** (published 2026-03-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @isdk/ai-tool
pnpm add @isdk/ai-tool
yarn add @isdk/ai-tool
bun add @isdk/ai-tool
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; large bundle; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2026-03-26 |
| First published | 2024-06-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.11.1 |
| Dependencies | 31 |
| Unpacked size | 103 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Riceball LEE |
| Maintainers | isdk |
| Keywords | ai, tool |

## Links

- npm: https://www.npmjs.com/package/@isdk/ai-tool
- Homepage: https://github.com/isdk/ai-tool.js/#readme
- npm.io page: https://npm.io/package/@isdk/ai-tool

## Dependencies (31)

- [yaml](https://npm.io/package/yaml.md) ^2.8.1
- [nanoid](https://npm.io/package/nanoid.md) ^5.1.5
- [util-ex](https://npm.io/package/util-ex.md) ^2.5.2
- [date-fns](https://npm.io/package/date-fns.md) ^4.1.0
- [memoizee](https://npm.io/package/memoizee.md) ^0.4.17
- [base32768](https://npm.io/package/base32768.md) ^5.0.0
- [events-ex](https://npm.io/package/events-ex.md) ^2.1.1
- [hash-wasm](https://npm.io/package/hash-wasm.md) ^4.12.0
- [jschardet](https://npm.io/package/jschardet.md) ^3.1.4
- [lodash-es](https://npm.io/package/lodash-es.md) ^4.17.21
- [mime-type](https://npm.io/package/mime-type.md) ^5.0.3
- [@isdk/hash](https://npm.io/package/@isdk/hash.md) ^0.1.1
- [@isdk/util](https://npm.io/package/@isdk/util.md) ^0.3.8
- [yaml-types](https://npm.io/package/yaml-types.md) ^0.4.0
- [@isdk/tool-rpc](https://npm.io/package/@isdk/tool-rpc.md) ^0.1.1
- [abstract-error](https://npm.io/package/abstract-error.md) ^2.0.0
- [custom-ability](https://npm.io/package/custom-ability.md) ^2.0.1
- [custom-factory](https://npm.io/package/custom-factory.md) 2.3.0
- [@isdk/tool-func](https://npm.io/package/@isdk/tool-func.md) ^0.1.1
- [secondary-cache](https://npm.io/package/secondary-cache.md) ^2.0.1
- [@isdk/tool-event](https://npm.io/package/@isdk/tool-event.md) ^0.1.2
- [load-config-file](https://npm.io/package/load-config-file.md) 2.1.0
- [property-manager](https://npm.io/package/property-manager.md) ^3.0.3
- [json-canonicalize](https://npm.io/package/json-canonicalize.md) ^2.0.0
- [package-directory](https://npm.io/package/package-directory.md) ^8.1.0
- [secure-json-parse](https://npm.io/package/secure-json-parse.md) ^4.0.0
- [@isdk/common-error](https://npm.io/package/@isdk/common-error.md) ^0.2.0
- [eventsource-parser](https://npm.io/package/eventsource-parser.md) ^3.0.6
- [@isdk/template-engines](https://npm.io/package/@isdk/template-engines.md) ^0.6.9
- [@huggingface/transformers](https://npm.io/package/@huggingface/transformers.md) ^3.8.1
- [@isdk/detect-text-language](https://npm.io/package/@isdk/detect-text-language.md) ^0.1.2

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.9.0 (latest) — 2026-03-26
- 0.8.2 — 2025-09-26
- 0.8.1 — 2025-09-26
- 0.8.0 — 2025-09-21
- 0.7.1 — 2025-09-07
- 0.7.0 — 2025-09-07
- 0.6.0 — 2025-04-04
- 0.5.8 — 2025-03-22
- 0.5.7 — 2025-03-17
- 0.5.6 — 2025-03-17
- 0.5.5 — 2025-03-16
- 0.5.4 — 2025-03-16
- 0.5.3 — 2025-03-16
- 0.5.2 — 2025-03-16
- 0.5.1 — 2025-03-16
- … 22 more at https://npm.io/package/@isdk/ai-tool/versions

## README

# @isdk/ai-tool

A powerful TypeScript framework for creating, managing, and communicating with modular functions. It's perfect for building AI agent tools, backend services, and extensible plugin systems with a clean, decoupled architecture.

## Core Features

- **Modular & Inheritable Tools:** Define functions in a structured way with a clear class hierarchy (`ToolFunc` -> `ServerTools` -> `ResServerTools`).
- **Pluggable RPC Transport:** Decouple your business logic from the network layer. Communicate between client and server using HTTP, IPC, or any custom protocol.
- **Pluggable PubSub Transport:** Create real-time, bidirectional event buses for features like notifications and live updates. Implementations for SSE (Server-Sent Events) and Electron IPC are included.
- **Global Registry:** Easily access any registered function from anywhere in your application.

## Installation

```bash
npm install @isdk/ai-tool
```

## Core Architecture: Tool Inheritance

`@isdk/ai-tool` is built on a foundation of extensible classes. Understanding their hierarchy and design is key to using the library effectively.

### Design Philosophy: Static vs. Instance

A key design principle in `ToolFunc` is the separation of roles between the static class and its instances:

- **The Static Class as Manager:** The static side of `ToolFunc` (e.g., `ToolFunc.register`, `ToolFunc.run`, `ToolFunc.get`) acts as a global **registry** and **executor**. It manages all tool definitions, allowing any part of your application to discover and run tools by name without needing a direct reference to the tool's instance.

- **The Instance as the Tool:** An instance (`new ToolFunc(...)`) represents a single, concrete **tool**. It holds the actual function logic, all its metadata (name, description, parameters), and any internal state.

This separation provides the best of both worlds: the power of object-oriented encapsulation for defining individual tools and the convenience of a globally accessible service for managing and executing them.

### Tool Inheritance Hierarchy

The library follows a clear inheritance path, adding specialized features at each level. For a detailed breakdown of each type and how they separate business logic from communication, see the [**Guide to Server & Client Tools**](./docs/server_client_tools.md).

**Server-Side Inheritance:**
`ToolFunc` -> `ServerTools` -> `RpcMethodsServerTool` -> `ResServerTools`

- **`ToolFunc`**: The base for any function, containing core logic and metadata. For more details, see the [ToolFunc Guide](./docs/toolFunc.md).
- **`ServerTools`**: Extends `ToolFunc` to be discoverable and callable by remote clients.
- **`RpcMethodsServerTool`**: Extends `ServerTools` to allow a single tool to expose multiple methods (e.g., a `Math` tool with `add` and `subtract` methods).
- **`ResServerTools`**: Extends `RpcMethodsServerTool` to automatically provide a resource-oriented (CRUD) interface.

**Client-Side Inheritance:**
A parallel hierarchy exists for the client, designed to seamlessly call the server-side tools.
`ToolFunc` -> `ClientTools` -> `RpcMethodsClientTool` -> `ResClientTools`

## Client-Server RPC with Transports

The framework shines in a client-server setup, allowing you to call backend functions as if they were local.

### Server-Side Example

Use `ServerTools` to define a backend function and `FastifyServerToolTransport` to expose it over HTTP.

```typescript
// server.ts
import { ServerTools, FastifyServerToolTransport } from '@isdk/ai-tool';

// Define a tool that can be called remotely
ServerTools.register({
  name: 'getUserProfile',
  params: { id: { type: 'string' } },
  func: async ({ id }: { id: string }) => {
    return { id, name: 'Jane Doe', email: 'jane.doe@example.com' };
  },
});

// Create a transport and mount the tools under the '/api' prefix
const serverTransport = new FastifyServerToolTransport();
serverTransport.mount(ServerTools, '/api');

// Start the server
serverTransport.start({ port: 3000 });
```

### Client-Side Example

The `mount` method handles both setting the transport and loading tool definitions from the server in one step.

```typescript
// client.ts
import { ClientTools, HttpClientToolTransport } from '@isdk/ai-tool';

async function main() {
  const apiRoot = 'http://localhost:3000/api';

  // 1. Setup the client transport and mount the tools
  const clientTransport = new HttpClientToolTransport(apiRoot);
  await clientTransport.mount(ClientTools);

  // 2. Get the remote tool and run it
  const getUserProfile = ClientTools.get('getUserProfile');
  const profile = await getUserProfile.run({ id: '123' });

  console.log(profile);
}
main();
```

> For a deeper dive into how transports work, see the [Transport Layer Guide](./docs/transport.md).

## Real-Time Events with PubSub

`@isdk/ai-tool` includes a powerful event system for real-time communication, built on a pluggable PubSub transport layer.

### Quick Example: SSE (Server-Sent Events)

**Server-Side:**
```typescript
// server.ts (additions)
import { EventServer, SseServerPubSubTransport, eventServer } from '@isdk/ai-tool';

// Set the PubSub transport for the EventServer
EventServer.setPubSubTransport(new SseServerPubSubTransport());
eventServer.register(); // Register the default event tool

// Now you can publish events from anywhere in your backend
setInterval(() => {
  EventServer.publish('server-time', { time: new Date().toISOString() });
}, 2000);
```

**Client-Side:**
```typescript
// client.ts (additions)
import { EventClient, SseClientPubSubTransport, eventClient, backendEventable } from '@isdk/ai-tool';

// Set the PubSub transport for the EventClient
EventClient.setPubSubTransport(new SseClientPubSubTransport());

// Make the client event-aware and register it
backendEventable(EventClient);
eventClient.setApiRoot('http://localhost:3000/api'); // Your API root
eventClient.register();

// Subscribe to and listen for server events
await eventClient.subscribe('server-time');
eventClient.on('server-time', (data) => {
  console.log('Live time from server:', data.time);
});
```

> For more detailed examples, including the Electron IPC transport, see the [**Real-time Events (PubSub) Guide**](./docs/pubsub.md).

## Contribution

If you would like to contribute to the project, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file for guidelines on how to get started.

## License

The project is licensed under the MIT License. See the [LICENSE-MIT](./LICENSE-MIT) file for more details.

## Credit

This project is inspired by and uses code from several excellent open-source projects:

* [@huggingface/jinja](https://github.com/huggingface/huggingface.js)
* [eventsource-parser](https://github.com/rexxars/eventsource-parser)
* [async-sema](https://github.com/vercel/async-sema)
* [modelfusion](https://github.com/vercel/modelfusion)

---
_Source: https://npm.io/package/@isdk/ai-tool · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._