@isdk/ai-tool 0.6.0 → 0.7.1

package/docs/{variables → api/variables}/mimeType.md

@@ -8,4 +8,4 @@
 
 > `const` **mimeType**: `MimeType`
 
-Defined in: node\_modules/.pnpm/mime-type@5.0.0/node\_modules/mime-type/src/with-db.d.ts:3
+Defined in: @isdk/ai-tools/node\_modules/.pnpm/mime-type@5.0.3/node\_modules/mime-type/src/with-db.d.ts:3

package/docs/{variables → api/variables}/uuidNIL.md

@@ -8,4 +8,4 @@
 
 > `const` **uuidNIL**: `"00000000-0000-0000-0000-000000000000"`
 
-Defined in: node\_modules/.pnpm/uuid@11.0.3/node\_modules/uuid/dist/esm-browser/nil.d.ts:1
+Defined in: @isdk/ai-tools/node\_modules/.pnpm/uuid@11.1.0/node\_modules/uuid/dist/esm-browser/nil.d.ts:1

package/docs/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/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`).

package/docs/toolFunc.md

@@ -0,0 +1,183 @@
+# `ToolFunc`: A Framework for Reusable Functions
+
+## Overview
+
+`ToolFunc` is a robust framework for creating, managing, and executing reusable functions within a JavaScript/TypeScript application. It provides a structured way to define functions with rich metadata, manage dependencies, and access them globally through a static registry. This system is designed to make functions self-documenting, modular, and easily discoverable, which is ideal for building complex tools, AI agent functions, or extensible plugin systems.
+
+## Key Features
+
+- **Rich Metadata**: Define functions with names, descriptions, titles, tags, and detailed parameter information.
+- **Static Registry**: A global registry allows any part of an application to access and execute functions by name without needing a direct instance.
+- **Dependency Management**: Declare dependencies on other `ToolFunc` instances, which are automatically registered when the parent function is registered.
+- **Lifecycle Hooks**: A `setup` hook provides a way to run initialization logic when a `ToolFunc` instance is created.
+- **Flexible Parameter Handling**: Supports both named-parameter objects and positional arguments for function execution.
+  - Note: All `ToolFunc` parameters are object-based, not positional.
+- **Aliasing and Tagging**: Assign aliases for alternative naming and tags for grouping and querying related functions.
+- **Streaming & Async Support**: Built-in support for functions that can stream output and declare asynchronous capabilities like cancellation.
+
+---
+
+## Core Concepts
+
+### 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.
+
+### 1. Defining a `ToolFunc`
+
+You create a function by instantiating the `ToolFunc` class with a configuration object (`FuncItem`). The only required properties are a `name` and a `func` implementation.
+
+```typescript
+import { ToolFunc } from './src/tool-func';
+
+const sayHello = new ToolFunc({
+  name: 'sayHello',
+  description: 'Prints a greeting to the console.',
+  title: 'Say Hello',
+  params: {
+    personName: { type: 'string', description: 'The name of the person to greet.', required: true }
+  },
+  func: (params) => {
+    console.log(`Hello, ${params.personName}!`);
+    return `Greeted ${params.personName}`;
+  }
+});
+```
+
+### 2. Registration
+
+For a `ToolFunc` to be globally accessible, it must be registered. Registration adds the function to a static `ToolFunc.items` map.
+
+```typescript
+// Register the instance you created
+sayHello.register();
+
+// You can also define and register in one go
+ToolFunc.register({
+    name: 'sayGoodbye',
+    func: () => console.log('Goodbye!')
+});
+```
+
+Once registered, the function can be accessed from anywhere in the application.
+
+### 3. Execution
+
+You can execute registered functions using the static `run` or `runSync` methods. The framework automatically handles passing parameters correctly.
+
+```typescript
+// Execute asynchronously
+async function greet() {
+  const result = await ToolFunc.run('sayHello', { personName: 'Alice' });
+  console.log(result); // Outputs: "Greeted Alice"
+}
+
+// Execute synchronously
+ToolFunc.runSync('sayGoodbye'); // Outputs: "Goodbye!"
+```
+
+---
+
+## Advanced Usage
+
+### Dependencies (`depends`)
+
+Use the `depends` property to ensure that other required `ToolFunc` instances are registered automatically. This is key to building modular tools.
+
+```typescript
+const helperFunc = new ToolFunc({ name: 'helper', func: () => 'world' });
+
+const mainFunc = new ToolFunc({
+  name: 'main',
+  depends: {
+    // This ensures helperFunc is registered when mainFunc is.
+    h: helperFunc,
+  },
+  func: function() { // `this` is the ToolFunc instance
+    const message = this.runSync('h');
+    return `Hello, ${message}`;
+  }
+});
+
+mainFunc.register(); // Both mainFunc and helperFunc are now registered.
+
+ToolFunc.runSync('main'); // Returns "Hello, world"
+```
+
+### Lifecycle Hook (`setup`)
+
+The `setup` method is called during the constructor's execution, allowing you to perform initialization logic on the instance.
+
+```typescript
+const myFunc = new ToolFunc({
+  name: 'myFunc',
+  customState: 'initial',
+  setup() {
+    // `this` refers to the ToolFunc instance
+    this.customState = 'configured';
+    console.log('Instance has been set up!');
+  },
+  func: function() {
+    return this.customState;
+  }
+});
+
+console.log(myFunc.runSync()); // Outputs: 'configured'
+```
+
+### Streaming Output (`stream` and `isStream`)
+
+To create a function that can optionally stream its output:
+
+1. Set `stream: true` in its definition. This marks it as *capable* of streaming.
+2. The `isStream(params)` method determines if a *specific call* should be streamed. The default logic checks for a `stream` parameter in the function's declaration and the runtime arguments.
+
+```typescript
+const streamableTask = new ToolFunc({
+  name: 'streamableTask',
+  stream: true, // 1. Mark as stream-capable
+  params: {
+    // 2. Declare a 'stream' parameter so the isStream method can check it
+    stream: { type: 'boolean', description: 'Whether to stream the output.' }
+  },
+  func: function(params) {
+    if (this.isStream(params)) {
+      // Return a ReadableStream for streaming output
+      return new ReadableStream(/* ... */);
+    } else {
+      // Return a regular value
+      return 'Completed';
+    }
+  }
+});
+```
+
+### Aliases and Tags
+
+Use `alias` to provide alternative names and `tags` to categorize functions.
+
+```typescript
+ToolFunc.register({
+  name: 'listUsers',
+  alias: ['ls', 'getUsers'],
+  tags: ['users', 'read'],
+  func: () => [/* ... */]
+});
+
+// These are now equivalent:
+const users1 = ToolFunc.get('listUsers');
+const users2 = ToolFunc.get('ls');
+
+// You can retrieve functions by tag:
+const userReaders = ToolFunc.getAllByTag('users');
+```
+
+## API Reference
+
+This document covers the main concepts and usage patterns. For a detailed API reference, please consult the TSDoc comments within the source code (`src/tool-func.ts`).