@isdk/ai-tool 0.5.0 → 0.5.1

package/docs/README.md

@@ -0,0 +1,250 @@
+**@isdk/ai-tool**
+
+***
+
+# @isdk/ai-tool
+
+A library for abstracting AI utility functions (`ToolFunc`), providing a series of convenient helper functions.
+
+**Note:** All `ToolFunc` parameters are object-based, not positional.
+
+## Installation
+
+1. Install the package:
+
+   ```bash
+   npm install @isdk/ai-tool
+   ```
+
+## Usage
+
+## ToolFunc
+
+Register ordinary functions as `ToolFunc`.
+
+### Example
+
+```ts
+import { ToolFunc } from '@isdk/ai-tool';
+
+// Register a function directly
+ToolFunc.register({
+  name: 'add',
+  description: 'Return the sum of a and b',
+  params: { a: { type: 'number' }, b: { type: 'number' } },
+  result: 'number',
+  func: ({ a, b }: { a: number; b: number }) => a + b,
+});
+
+console.log('Result:', ToolFunc.runSync('add', { a: 1, b: 2 }));
+// Result: 3
+```
+
+Properties
+
+* `func`: The main body of the tool function.
+* `name`: Name of the tool function.
+* `params`: Parameter schema for the tool function.
+* `result`: Return type of the tool function.
+* `scope`: Scope of the function.
+* `description`: Description of the tool function.
+* `setup`: Executed during the construction of the ToolFunc instance.
+* `depends`: Dependencies on other ToolFunc instances.
+
+### ServerTools (extends ToolFunc)
+
+Server-side AI tool functions.
+
+**Features**
+
+* Allows exporting the function body as a string for local execution.
+* Provides a static `toJSON()` method to export all service API definitions.
+
+```ts
+interface ServerFuncItem extends FuncItem {
+  apiRoot?: string
+  /**
+   * API request method, can be 'get' or 'post'
+   */
+  action?: 'get'|'post'
+  // Options for the Node.js fetch function
+  fetchOptions?: any
+  // Whether to allow exporting the func body itself, default to false
+  allowExportFunc?: boolean
+}
+```
+
+Usage: Parameters are sent via query string for GET requests and in the body for POST requests.
+
+### ClientTools (extends ToolFunc)
+
+Used to call remote AI tool functions (ServerTools).
+
+**Features**
+
+* Supports loading all remote calls with static loadFromSync(items) and static async loadFrom().
+* Prioritizes local execution over remote calls.
+
+```ts
+interface ClientFuncItem extends FuncItem {
+  apiRoot?: string
+  action?: 'get'|'post'
+  fetchOptions?: any
+}
+```
+
+### ResServerTools
+
+Resource-based server tools, where resources are named ToolFunc.
+
+#### Methods
+
+* `GET /api/res/:id`: Get resource.
+* `GET /api/res`: List resources.
+* `POST /api/res`: Create resource.
+* `PUT /api/res/:id`: Update resource.
+* `DELETE /api/res/:id`: Delete resource.
+
+#### Custom Methods
+
+Methods prefixed with `$` are custom resource methods, accessible via `POST`.
+
+Example
+
+```ts
+class TestResTool extends ResServerTools {
+  items: any = {}
+  params: FuncParams = {
+    'id': {type: 'number'},
+    'val': {type: 'any'},
+  }
+  $customMethod({id}: ResServerFuncParams) {
+    if (id) {
+      const item = this.items[id]
+      if (!item) {
+        throw new NotFoundError(id, 'res')
+      }
+      return {name: 'customMethod', id, item}
+    }
+  }
+  get({id}: ResServerFuncParams) {
+    if (id) {
+      const item = this.items[id]
+      if (!item) {
+        throw new NotFoundError(id, 'res')
+      }
+      return item
+    }
+  }
+  post({id, val}: ResServerFuncParams) {
+    if (id !== undefined && val !== undefined) {
+      this.items[id] = val
+      return {id}
+    } else {
+      throwError('id or val is undefined')
+    }
+  }
+  list() {
+    return Object.keys(this.items)
+  }
+  delete({id}: ResServerFuncParams) {
+    if (id) {
+      const item = this.items[id]
+      if (item === undefined) {
+        throw new NotFoundError(id, 'res')
+      }
+      delete this.items[id]
+      return {id}
+    }
+  }
+}
+ResServerTools.apiRoot = apiRoot
+const res = new TestResTool('res')
+res.register()
+```
+
+### ResClientTools
+
+Resource-based client tools that generate methods based on ServerTools agreements.
+
+Example
+
+```ts
+ResClientTools.apiRoot = apiRoot
+await ResClientTools.loadFrom()
+
+const resFunc = ResClientTools.getFunc(funcName)
+if (resFunc) {
+  let result = await res.post({id: '...', val: '...'})
+  result = await res.put({id: '...', val: '...'})
+  result = await res.get({id: '...'})
+  result = await res.customMethod({id: '...'})
+}
+```
+
+### SSE (Server-Sent Events)
+
+Endpoints
+
+* `GET /api/event`: List server event channel (stream).
+* `POST /api/event`: Subscribe to server events.
+* `DELETE /api/event`: Unsubscribe from server events.
+* `PUT /api/event`: Publish messages to server events.
+
+### EventClient
+
+The `EventClient` component facilitates communication between the client and server through Server-Sent Events (SSE). Its primary responsibilities include subscribing to server events and publishing messages to the server.
+
+#### Key Features
+
+- **Subscription**: Subscribes to server events and forwards them to the local client's event bus.
+- **Publication**: Publishes messages to the server.
+
+#### EventClient Methods
+
+- `initEventSource(events)`: Specifies which events to receive from the server. If `events` is not provided, all events are received.
+- `subscribe(events)`: Subscribes to specified server events and forwards them to the local event bus.
+  - Note: It's important to distinguish between local and server-originated messages. Server messages that were previously forwarded from local events should not be re-forwarded to avoid infinite loops.
+- `unsubscribe(events)`: Cancels subscriptions to specified server events.
+- `forwardEvent(events)`: Forwards specific local events to the server.
+- `unforwardEvent(events)`: Stops forwarding specific local events to the server.
+
+#### Considerations
+
+- Local events that need to be forwarded to the server can be managed independently through the `forwardEvent` method.
+- Event handling logic should be decoupled from the core functionality of `ToolFunc` to maintain flexibility and separation of concerns.
+
+### EventServer
+
+The `EventServer` component manages server-side event processing, including publishing and subscribing to events.
+
+**Key Features**
+
+- **Publishing**: Publishes events to clients via SSE.
+- **Subscribing**: Manages subscriptions to events on the server side.
+
+**Actions**
+
+- `pub`: Publishes an SSE event.
+- `sub`: Subscribes to server events.
+- `unsub`: Unsubscribes from server events.
+
+**Usage**
+
+- Functions without an `act` or with only `events` specified are used for server-side event handling.
+- Functions with an `act` define specific actions such as publishing, subscribing, or unsubscribing from events.
+
+## 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
+
+* [@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/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Please feel free to file GitHub Issues or propose Pull Requests. We're always happy to discuss improvements to this library!
+
+## Testing
+
+```shell
+npm test
+```
+
+## Releasing
+
+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
+```

package/docs/_media/LICENSE-MIT

@@ -0,0 +1,22 @@
+Copyright (c) 2023 Riceball LEE
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/docs/classes/AbortError.md

@@ -0,0 +1,366 @@
+[**@isdk/ai-tool**](../README.md)
+
+***
+
+[@isdk/ai-tool](../globals.md) / AbortError
+
+# Class: AbortError
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:142
+
+BaseError class that extends the Error class.
+
+## Example
+
+```ts
+// Create a custom error
+class CustomError extends BaseError {
+  static code = 'customError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+// Throw the custom error
+throw new CustomError('This is a custom error');
+```
+
+## Description
+
+This class is used to create custom errors that extend the built-in Error class. It provides a way to define custom error codes and additional data associated with the error.
+
+## Method
+
+toJSON - Returns a JSON representation of the error.
+
+## Method
+
+fromJSON - Creates a new BaseError instance from a JSON representation.
+
+## Extends
+
+- [`CommonError`](CommonError.md)
+
+## Constructors
+
+### new AbortError()
+
+> **new AbortError**(`what`?, `name`?): [`AbortError`](AbortError.md)
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:144
+
+#### Parameters
+
+##### what?
+
+`string`
+
+##### name?
+
+`string` | `Record`\<`string`, `any`\>
+
+#### Returns
+
+[`AbortError`](AbortError.md)
+
+#### Overrides
+
+[`CommonError`](CommonError.md).[`constructor`](CommonError.md#constructors)
+
+## Properties
+
+### caller
+
+> **caller**: `string`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:63
+
+The name of the function that threw the error.
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`caller`](CommonError.md#caller)
+
+***
+
+### cause?
+
+> `optional` **cause**: `unknown`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.2/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`cause`](CommonError.md#cause)
+
+***
+
+### code
+
+> **code**: `ErrorCodeType`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:64
+
+the error code
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`code`](CommonError.md#code)
+
+***
+
+### data?
+
+> `optional` **data**: `any`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:65
+
+Additional data associated with the error.
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`data`](CommonError.md#data)
+
+***
+
+### message
+
+> **message**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.2/node\_modules/typescript/lib/lib.es5.d.ts:1077
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`message`](CommonError.md#message-1)
+
+***
+
+### name
+
+> **name**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.2/node\_modules/typescript/lib/lib.es5.d.ts:1076
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`name`](CommonError.md#name-1)
+
+***
+
+### stack?
+
+> `optional` **stack**: `string`
+
+Defined in: node\_modules/.pnpm/typescript@5.7.2/node\_modules/typescript/lib/lib.es5.d.ts:1078
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`stack`](CommonError.md#stack)
+
+***
+
+### code
+
+> `static` **code**: [`ErrorCode`](../enumerations/ErrorCode.md)
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:143
+
+The error code associated with the error.
+
+#### Overrides
+
+[`CommonError`](CommonError.md).[`code`](CommonError.md#code-1)
+
+***
+
+### prepareStackTrace()?
+
+> `static` `optional` **prepareStackTrace**: (`err`, `stackTraces`) => `any`
+
+Defined in: node\_modules/.pnpm/@types+node@22.10.5/node\_modules/@types/node/globals.d.ts:143
+
+Optional override for formatting stack traces
+
+#### Parameters
+
+##### err
+
+`Error`
+
+##### stackTraces
+
+`CallSite`[]
+
+#### Returns
+
+`any`
+
+#### See
+
+https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`prepareStackTrace`](CommonError.md#preparestacktrace)
+
+***
+
+### stackTraceLimit
+
+> `static` **stackTraceLimit**: `number`
+
+Defined in: node\_modules/.pnpm/@types+node@22.10.5/node\_modules/@types/node/globals.d.ts:145
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`stackTraceLimit`](CommonError.md#stacktracelimit)
+
+## Methods
+
+### fromJSON()
+
+> **fromJSON**(`json`): [`BaseError`](BaseError.md)
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:93
+
+Creates a new BaseError instance from a JSON representation.
+
+#### Parameters
+
+##### json
+
+`any`
+
+A JSON representation of the error.
+
+#### Returns
+
+[`BaseError`](BaseError.md)
+
+A new BaseError instance.
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`fromJSON`](CommonError.md#fromjson)
+
+***
+
+### toJSON()
+
+> **toJSON**(): `any`
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:86
+
+Returns a JSON representation of the error.
+
+#### Returns
+
+`any`
+
+A JSON representation of the error.
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`toJSON`](CommonError.md#tojson)
+
+***
+
+### captureStackTrace()
+
+> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`
+
+Defined in: node\_modules/.pnpm/@types+node@22.10.5/node\_modules/@types/node/globals.d.ts:136
+
+Create .stack property on a target object
+
+#### Parameters
+
+##### targetObject
+
+`object`
+
+##### constructorOpt?
+
+`Function`
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`captureStackTrace`](CommonError.md#capturestacktrace)
+
+***
+
+### create()
+
+> `static` **create**(`__namedParameters`): [`CommonError`](CommonError.md)
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:96
+
+#### Parameters
+
+##### \_\_namedParameters
+
+###### code?
+
+`string` \| `number`
+
+###### data?
+
+`any`
+
+###### error
+
+`string`
+
+###### name?
+
+`string`
+
+#### Returns
+
+[`CommonError`](CommonError.md)
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`create`](CommonError.md#create)
+
+***
+
+### createErrorClass()
+
+> `static` **createErrorClass**(`aType`, `aErrorCode`?, `ParentErrorClass`?): *typeof* [`BaseError`](BaseError.md)
+
+Defined in: node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:66
+
+Create an Error Class
+
+#### Parameters
+
+##### aType
+
+`string`
+
+the error type(class) name
+
+##### aErrorCode?
+
+`string` | `number` | *typeof* `AbstractError`
+
+##### ParentErrorClass?
+
+*typeof* [`BaseError`](BaseError.md)
+
+the parent error class. defaults to AbstractError
+
+#### Returns
+
+*typeof* [`BaseError`](BaseError.md)
+
+the new Error Class
+
+#### Inherited from
+
+[`CommonError`](CommonError.md).[`createErrorClass`](CommonError.md#createerrorclass)