@isdk/ai-tool 0.6.0 → 0.7.1

package/docs/api/README.md

@@ -0,0 +1,165 @@
+**@isdk/ai-tool**
+
+***
+
+# @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**](_media/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](_media/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](_media/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**](_media/pubsub.md).
+
+## Contribution
+
+If you would like to contribute to the project, please read the [CONTRIBUTING.md](_media/CONTRIBUTING.md) file for guidelines on how to get started.
+
+## License
+
+The project is licensed under the MIT License. See the [LICENSE-MIT](_media/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)

package/docs/{_media → api/_media}/CONTRIBUTING.md

@@ -5,7 +5,7 @@ Please feel free to file GitHub Issues or propose Pull Requests. We're always ha
 ## Testing
 
 ```shell
-npm test
+pnpm test
 ```
 
 ## Releasing
@@ -13,6 +13,6 @@ npm test
 Releases are supposed to be done from master, version bumping is automated through [`standard-version`](https://github.com/absolute-version/commit-and-tag-version):
 
 ```shell
-npm run release -- --dry-run  # verify output manually
-npm run release               # follow the instructions from the output of this command
+pnpm run release -- --dry-run  # verify output manually
+pnpm run release               # follow the instructions from the output of this command
 ```

package/docs/api/_media/pubsub.md

@@ -0,0 +1,326 @@
+# Developer's Guide: Real-time Events with EventServer & EventClient
+
+This guide provides a comprehensive overview of the `EventServer` and `EventClient` tools, a powerful system for real-time, bidirectional communication. It is built on a **pluggable PubSub transport layer**, making it independent of the underlying communication protocol. You can use Server-Sent Events (SSE), WebSockets, IPC, or any other protocol by providing a corresponding transport implementation.
+
+**Prerequisite:** This document assumes you understand the base transport layer. If not, please review the [`transport_readme.md`](./transport_readme.md) first.
+
+## Core Concept: The Unified Event Bus
+
+The primary goal of this system is to create a seamless event bus that spans both the server and the client. It uses an abstract, pluggable PubSub transport for server-to-client messages and standard RPC calls for client-to-server messages.
+
+The key feature is the ability to **"forward"** events. You can configure the server to automatically listen for events on its internal, global `eventBus` and relay them to clients. Likewise, you can configure the client to forward its local events to the server. This creates a powerful, decoupled architecture where different parts of your application can communicate without direct dependencies.
+
+### Aspect-Oriented Programming (AoP) and Event Emitters
+
+A crucial concept is that `EventClient` (and `ClientTools` in general) can be enhanced with event emitter capabilities. By using a library like `events-ex`, you can give your client-side tool instances standard `on`, `off`, and `emit` methods. This allows `EventClient` to act as a local event bus that is transparently synchronized with the server.
+
+## Example 1: HTTP and Server-Sent Events (SSE)
+
+### Architecture (SSE)
+
+The following diagram illustrates how the components interact when using the provided SSE-based transport. Other transports (like WebSockets or IPC) would follow a similar pattern.
+
+```mermaid
+graph TD
+    subgraph Client-Side
+        C_App[Client Application]
+        C_EventBus(Local Event Emitter)
+        EC[EventClient] -- "uses" --> C_PubSub[SseClientPubSubTransport]
+        C_Transport[HttpClientToolTransport]
+
+        C_App -- "emit/on" --> C_EventBus
+        EC -- "decorated with" --> C_EventBus
+        C_PubSub -- "HTTP GET (SSE)" --> S_PubSub
+        EC -- "RPC calls" --> C_Transport
+    end
+
+    subgraph Server-Side
+        S_Transport[FastifyServerToolTransport] -- "receives RPC" --> ES[EventServer]
+        ES -- "uses" --> S_PubSub[SseServerPubSubTransport]
+        S_PubSub -- "handles SSE connections" --> ES
+        ES -- "interacts with" --> S_EventBus[Global Server EventBus]
+        OtherServices[Other Server Logic] -- "emit/on" --> S_EventBus
+    end
+
+    subgraph "Network (HTTP)"
+        C_Transport -- "RPC: POST /api/event" --> S_Transport
+    end
+```
+
+### Server-Side Setup (SSE)
+
+In your server setup, you must first tell `EventServer` which transport to use, then register the `eventServer` instance.
+
+```typescript
+// In your server entry file (e.g., server.ts)
+import {
+  eventServer,
+  FastifyServerToolTransport,
+  ResServerTools,
+  EventServer, // Import EventServer class
+  SseServerPubSubTransport // Import the SSE transport
+} from '@isdk/ai-tool';
+
+async function main() {
+  // **Crucial Step: Set the PubSub transport for the server**
+  EventServer.setPubSubTransport(new SseServerPubSubTransport());
+
+  // Register the eventServer tool instance
+  eventServer.register();
+
+  const serverTransport = new FastifyServerToolTransport();
+  // Mount the base class; the transport finds all registered tools
+  serverTransport.mount(ResServerTools, '/api');
+
+  // ... start server
+  await serverTransport.start({port: 3000})
+}
+```
+
+### Client-Side Setup (SSE)
+
+On the client, you must set the appropriate PubSub transport (matching the server's), enhance the `EventClient` with `EventEmitter` capabilities, and register the instance.
+
+```typescript
+// In your client-side code
+import {
+  backendEventable,
+  EventClient,
+  eventClient,
+  HttpClientToolTransport,
+  ResClientTools,
+  SseClientPubSubTransport // Import the SSE transport
+} from '@isdk/ai-tool';
+
+async function main() {
+  const apiRoot = 'http://localhost:3003/api';
+  const clientTransport = new HttpClientToolTransport(apiRoot);
+  await clientTransport.mount(ResClientTools);
+
+  // **Crucial Step 1: Set the PubSub transport for the client**
+  EventClient.setPubSubTransport(new SseClientPubSubTransport());
+
+  // **Crucial Step 2: Make the client eventable**
+  backendEventable(EventClient);
+  eventClient.register();
+
+  // Now you can use eventClient.on, .off, .emit
+}
+```
+
+---
+
+## Example 2: Electron IPC Transport
+
+This transport uses Electron's Inter-Process Communication (IPC) to create an event bus between the main process (server) and renderer processes (clients).
+
+### Server-Side Setup (Electron Main Process)
+
+In your Electron main process, you instantiate an `ElectronServerPubSubTransport` with a unique namespace. This namespace acts like an `apiRoot` and ensures that different event buses don't conflict.
+
+```typescript
+// In your Electron main process (e.g., main.ts)
+import {
+  EventServer,
+  eventServer,
+  ElectronServerPubSubTransport,
+} from '@isdk/ai-tool';
+
+// 1. Define a unique namespace for this event bus
+const electronApiRoot = '/electron/events';
+
+// 2. Create a transport instance for this specific namespace
+const electronTransport = new ElectronServerPubSubTransport(electronApiRoot);
+
+// 3. Set the transport on the EventServer
+// Note: This is a static property. For multiple, different event servers
+// (e.g., one for SSE, one for Electron), you would create subclasses of EventServer
+// to hold each static transport instance separately.
+EventServer.setPubSubTransport(electronTransport);
+
+// 4. Register the eventServer tool instance. It will now use the Electron transport.
+eventServer.register();
+
+// Now you can use the global eventBus to emit events, and the EventServer
+// will forward them to any connected renderer process.
+```
+
+### Client-Side Setup (Electron Renderer Process)
+
+In the renderer process, you must use the same namespace (`apiRoot`) to connect to the correct event bus in the main process.
+
+**Important:** The `EventClient` still relies on an RPC mechanism for actions like `subscribe` and `unsubscribe`. You must have a corresponding RPC transport set up between the renderer and main process for the full functionality to work. The example below focuses only on setting up the PubSub portion.
+
+```typescript
+// In your Electron renderer process (e.g., preload.ts or renderer.ts)
+import {
+  EventClient,
+  eventClient,
+  ElectronClientPubSubTransport,
+  backendEventable,
+} from '@isdk/ai-tool';
+
+// 1. The apiRoot MUST match the namespace used in the main process
+const electronApiRoot = '/electron/events';
+
+// 2. Set the PubSub transport on the EventClient class
+EventClient.setPubSubTransport(new ElectronClientPubSubTransport());
+
+// 3. Make the EventClient class event-aware
+backendEventable(EventClient);
+
+// 4. Configure the eventClient INSTANCE
+// This tells the client which event bus to connect to.
+eventClient.setApiRoot(electronApiRoot);
+eventClient.register();
+
+// 5. Now you can use the event client
+async function setupEvents() {
+  await eventClient.subscribe('some-event-from-main');
+
+  eventClient.on('some-event-from-main', (data) => {
+    console.log('Received event from main process:', data);
+  });
+
+  // Forward a local event to the main process
+  eventClient.forwardEvent('event-from-renderer');
+  eventClient.emit('event-from-renderer', { my: 'data' });
+}
+
+setupEvents();
+```
+
+---
+
+## General Usage (Transport-Agnostic)
+
+Once the setup is complete, the API for using the event bus is the same regardless of the underlying transport.
+
+### Forwarding and Publishing Events (Server-Side)
+
+The server can push events to clients either by forwarding them from a central event bus or by publishing them directly. With the latest updates, the `publish` method now supports targeted delivery to specific clients, in addition to broadcasting.
+
+**Note:** The availability of targeted publishing depends on the underlying transport implementation. While the `EventServer` API supports it, some transports (like the current SSE transport) may only be capable of broadcasting.
+
+```typescript
+import { eventServer, EventServer } from '@isdk/ai-tool';
+import { event } from '@isdk/ai-tool/funcs/event'; // The global eventBus
+
+const eventBus = event.runSync();
+
+// **Forwarding (Recommended)**
+// Automatically relay events from the global eventBus to subscribed clients.
+eventServer.forward(['user-updated', 'item-added']);
+
+// Now, any other part of your server can simply emit events on the bus:
+function updateUser(user: any) {
+  eventBus.emit('user-updated', { userId: user.id, status: 'active' });
+}
+
+// **Direct Publishing**
+// The `EventServer.publish` method allows sending an event directly to clients.
+// Its signature is: `publish(event: string, data: any, target?: { clientId: string | string[] })`.
+
+// 1. Broadcast to all clients subscribed to 'broadcast-message'.
+// This is the default behavior when `target` is omitted.
+function sendBroadcast() {
+    EventServer.publish('broadcast-message', { message: 'Server is restarting soon!' });
+}
+
+// 2. Send a targeted event to a specific client.
+// This requires knowing the `clientId` of the recipient.
+function sendDirectMessage(clientId: string, message: string) {
+    const target = { clientId };
+    EventServer.publish('private-message', { text: message }, target);
+}
+
+// 3. Send an event to a group of specific clients.
+function sendToGroup(clientIds: string[], message: string) {
+    const target = { clientId: clientIds };
+    EventServer.publish('group-message', { text: message }, target);
+}
+
+// **Receiving Client Events**
+// Listen for events that were published or forwarded from a client.
+eventBus.on('client-action', (data: any, event: any) => {
+  console.log(`Received event "$\{event.type\}" from a client:`, data);
+});
+```
+
+### Subscribing, Listening, and Publishing (Client-Side)
+
+```typescript
+// **Subscribe and Listen**
+await eventClient.subscribe(['user-updated', 'broadcast-message']);
+
+eventClient.on('user-updated', (data: any) => {
+  console.log('User updated on server!', data);
+});
+
+// **Publish an Event to the Server**
+eventClient.publish({
+    event: 'client-action',
+    data: { action: 'button-click', value: 123 }
+});
+
+// **Forwarding Client Events (Recommended)**
+eventClient.forwardEvent(['user-settings-changed']);
+
+function onSettingsSave(newSettings: any) {
+    eventClient.emit('user-settings-changed', newSettings);
+}
+```
+
+This transport-agnostic architecture provides a clean, powerful, and decoupled way to build real-time, interactive applications. By separating the event logic from the communication protocol, you can choose the best transport for your needs while maintaining a consistent, unified event model.
+
+---
+
+## Implementing a Custom PubSub Transport
+
+For developers who need to integrate a different messaging protocol (e.g., WebSockets, MQTT), you can create your own transport by implementing the `IPubSubServerTransport` interface from `@isdk/ai-tool/transports/pubsub/server`.
+
+The core interface is defined as follows:
+
+```typescript
+export interface IPubSubServerTransport {
+  readonly name: string;
+  readonly protocol: string;
+
+  // Optional: For transports that need to hook into an HTTP server
+  mount?: (path: string, options?: Record<string, any>) => void;
+
+  // Establish a connection with a client and subscribe them to events.
+  // The `options` object is a generic container for transport-specific
+  // parameters, like HTTP request/response objects for SSE.
+  subscribe: (
+    events?: string[],
+    options?: {
+      req?: any;
+      res?: any;
+      clientId?: string;
+      [k: string]: any;
+    }
+  ) => PubSubClient; // Return a client object, minimally with a `clientId`.
+
+  // Publish an event from the server to clients.
+  // The `target` parameter allows for broadcasting (default) or
+  // targeted delivery to specific client IDs.
+  publish: (
+    event: string,
+    data: any,
+    target?: { clientId?: string | string[] }
+  ) => void;
+
+  // Lifecycle hooks to let the EventServer know about connections.
+  onConnection: (cb: (session: PubSubServerSession) => void) => void;
+  onDisconnect: (cb: (session: PubSubServerSession) => void) => void;
+
+  // Optional: For bidirectional transports (e.g., WebSockets)
+  // to handle messages received from the client.
+  onMessage?: (
+    cb: (session: PubSubServerSession, event: string, data: any) => void
+  ) => void;
+}
+```
+
+By implementing this interface, your custom transport can be plugged directly into the `EventServer` using `EventServer.setPubSubTransport(new YourCustomTransport())`, enabling the entire real-time event system over your chosen protocol.

package/docs/api/_media/server_client_tools.md

@@ -0,0 +1,88 @@
+# Guide: Server & Client Tool Types
+
+This guide provides a detailed description of the different `ServerTools` and `ClientTools` subclasses. It focuses on their specific purpose and how each one separates its business logic from the communication logic handled by the transport layer.
+
+## 1. `ServerTools` / `ClientTools`
+
+This is the most fundamental pair for client-server communication.
+
+### `ServerTools`
+
+- **Purpose:** To define a single, remotely callable function.
+- **Business Logic:** Your code is placed entirely within the `func` property when the tool is defined. This function contains the logic you want to execute on the server.
+- **Communication Logic:** This class has **no** communication logic. It is a simple container for your business logic. The transport layer is entirely responsible for receiving a network request and invoking the tool's `func`.
+
+```typescript
+// Business logic is self-contained in 'func'.
+ServerTools.register({
+  name: 'mySimpleTool',
+  func: async (params) => {
+    // ... your logic here ...
+    return { success: true, ...params };
+  },
+});
+```
+
+### `ClientTools`
+
+- **Purpose:** To act as a local proxy for a remote `ServerTools` instance.
+- **Business Logic:** This class contains **no** business logic.
+- **Communication Logic:** When you call `.run()` on a `ClientTools` instance, its only job is to delegate the call to the configured **client transport**. The transport handles all aspects of serialization, network requests, and response handling.
+
+---
+
+## 2. `RpcMethodsServerTool` / `RpcMethodsClientTool`
+
+This pair is designed to group multiple related functions into a single, cohesive tool, like methods on a class.
+
+### `RpcMethodsServerTool`
+
+- **Purpose:** To serve as a container for multiple, related functions under a single tool name.
+- **Business Logic:** You define your logic in class methods prefixed with a `$` (e.g., `$add`, `$subtract`). Each method represents a distinct operation.
+- **Communication Logic:** This class contains a small amount of **routing logic**. Its main `func` (which is invoked by the transport) acts as a simple dispatcher. It inspects the `act` parameter from the incoming request and calls the corresponding internal `$` method. It does not handle any direct network communication.
+
+```typescript
+// Business logic is in the $add and $subtract methods.
+class CalculatorTool extends RpcMethodsServerTool {
+  $add({ a, b }) { return a + b; }
+  $subtract({ a, b }) { return a - b; }
+}
+
+// The main 'func' inherited from the base class handles the routing.
+new CalculatorTool('calculator').register();
+```
+
+### `RpcMethodsClientTool`
+
+- **Purpose:** To be a user-friendly proxy for a remote `RpcMethodsServerTool`.
+- **Business Logic:** None.
+- **Communication Logic:** This class has more advanced communication logic than a basic `ClientTools` instance. When it's created, it dynamically adds proxy methods to itself (e.g., `.add()`, `.subtract()`). When you call one of these proxy methods, it automatically constructs the correct request body (e.g., `{ act: '$add', a, b }`) before passing it to the client transport for sending.
+
+---
+
+## 3. `ResServerTools` / `ResClientTools`
+
+This is the highest-level abstraction, designed for creating resource-oriented APIs that follow RESTful conventions.
+
+### `ResServerTools`
+
+- **Purpose:** To provide a conventional, resource-oriented (CRUD) API.
+- **Business Logic:** You place your logic in conventionally-named methods like `get`, `list`, `post`, `put`, and `delete`.
+- **Communication Logic:** This class has the most advanced **routing logic**. It is designed to work with a transport that can provide HTTP context (like the verb and URL parameters). It maps HTTP request details (e.g., `GET /api/users/123`) to the appropriate business logic method (e.g., `get({ id: '123' })`). It still relies on the transport to handle the actual network connection.
+
+```typescript
+// Business logic is in the get, list, etc. methods.
+class UserResource extends ResServerTools {
+  get({ id }) { /* ... find user by id ... */ }
+  list() { /* ... return all users ... */ }
+}
+
+// The tool's internal logic maps HTTP requests to these methods.
+new UserResource('users').register();
+```
+
+### `ResClientTools`
+
+- **Purpose:** To be an intuitive proxy for a remote `ResServerTools` instance.
+- **Business Logic:** None.
+- **Communication Logic:** It provides a conventional client-side API (e.g., `.get()`, `.list()`). Calling one of these methods signals to the client transport *how* to construct the underlying HTTP request. For example, calling `userClient.get({ id: '123' })` instructs the transport to make an `HTTP GET` request to the appropriate URL (`/api/users/123`).