@isdk/ai-tool 0.3.0 → 0.5.0

package/docs/README.md

@@ -1,250 +0,0 @@
-**@isdk/ai-tool** • [**Docs**](globals.md)
-
-***
-
-# @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

@@ -1,18 +0,0 @@
-# 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

@@ -1,22 +0,0 @@
-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

@@ -1,368 +0,0 @@
-[**@isdk/ai-tool**](../README.md) • **Docs**
-
-***
-
-[@isdk/ai-tool](../globals.md) / AbortError
-
-# Class: AbortError
-
-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)
-
-#### Parameters
-
-• **what?**: `string`
-
-• **name?**: `string` \| `Record`\<`string`, `any`\>
-
-#### Returns
-
-[`AbortError`](AbortError.md)
-
-#### Overrides
-
-[`CommonError`](CommonError.md).[`constructor`](CommonError.md#constructors)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:144
-
-## Properties
-
-### caller
-
-> **caller**: `string`
-
-The name of the function that threw the error.
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`caller`](CommonError.md#caller)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:63
-
-***
-
-### cause?
-
-> `optional` **cause**: `unknown`
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`cause`](CommonError.md#cause)
-
-#### Defined in
-
-node\_modules/.pnpm/typescript@5.6.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24
-
-***
-
-### code
-
-> **code**: `ErrorCodeType`
-
-the error code
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`code`](CommonError.md#code)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:64
-
-***
-
-### data?
-
-> `optional` **data**: `any`
-
-Additional data associated with the error.
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`data`](CommonError.md#data)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:65
-
-***
-
-### message
-
-> **message**: `string`
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`message`](CommonError.md#message)
-
-#### Defined in
-
-node\_modules/.pnpm/typescript@5.6.3/node\_modules/typescript/lib/lib.es5.d.ts:1077
-
-***
-
-### name
-
-> **name**: `string`
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`name`](CommonError.md#name)
-
-#### Defined in
-
-node\_modules/.pnpm/typescript@5.6.3/node\_modules/typescript/lib/lib.es5.d.ts:1076
-
-***
-
-### stack?
-
-> `optional` **stack**: `string`
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`stack`](CommonError.md#stack)
-
-#### Defined in
-
-node\_modules/.pnpm/typescript@5.6.3/node\_modules/typescript/lib/lib.es5.d.ts:1078
-
-***
-
-### code
-
-> `static` **code**: [`ErrorCode`](../enumerations/ErrorCode.md)
-
-The error code associated with the error.
-
-#### Overrides
-
-[`CommonError`](CommonError.md).[`code`](CommonError.md#code-1)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:143
-
-***
-
-### prepareStackTrace()?
-
-> `static` `optional` **prepareStackTrace**: (`err`, `stackTraces`) => `any`
-
-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)
-
-#### Defined in
-
-node\_modules/.pnpm/@types+node@22.7.6/node\_modules/@types/node/globals.d.ts:143
-
-***
-
-### stackTraceLimit
-
-> `static` **stackTraceLimit**: `number`
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`stackTraceLimit`](CommonError.md#stacktracelimit)
-
-#### Defined in
-
-node\_modules/.pnpm/@types+node@22.7.6/node\_modules/@types/node/globals.d.ts:145
-
-## Methods
-
-### fromJSON()
-
-> **fromJSON**(`json`): [`BaseError`](BaseError.md)
-
-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)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:93
-
-***
-
-### toJSON()
-
-> **toJSON**(): `any`
-
-Returns a JSON representation of the error.
-
-#### Returns
-
-`any`
-
-A JSON representation of the error.
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`toJSON`](CommonError.md#tojson)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:86
-
-***
-
-### captureStackTrace()
-
-> `static` **captureStackTrace**(`targetObject`, `constructorOpt`?): `void`
-
-Create .stack property on a target object
-
-#### Parameters
-
-• **targetObject**: `object`
-
-• **constructorOpt?**: `Function`
-
-#### Returns
-
-`void`
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`captureStackTrace`](CommonError.md#capturestacktrace)
-
-#### Defined in
-
-node\_modules/.pnpm/@types+node@22.7.6/node\_modules/@types/node/globals.d.ts:136
-
-***
-
-### create()
-
-> `static` **create**(`__namedParameters`): [`CommonError`](CommonError.md)
-
-#### Parameters
-
-• **\_\_namedParameters**
-
-• **\_\_namedParameters.code?**: `string` \| `number`
-
-• **\_\_namedParameters.data?**: `any`
-
-• **\_\_namedParameters.error**: `string`
-
-• **\_\_namedParameters.name?**: `string`
-
-#### Returns
-
-[`CommonError`](CommonError.md)
-
-#### Inherited from
-
-[`CommonError`](CommonError.md).[`create`](CommonError.md#create)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:96
-
-***
-
-### createErrorClass()
-
-> `static` **createErrorClass**(`aType`, `aErrorCode`?, `ParentErrorClass`?): *typeof* [`BaseError`](BaseError.md)
-
-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)
-
-#### Defined in
-
-node\_modules/.pnpm/@isdk+common-error@0.1.3/node\_modules/@isdk/common-error/dist/index.d.ts:66