@isdk/ai-tool 0.6.0 → 0.7.1

package/docs/api/interfaces/IPubSubServerTransport.md

@@ -0,0 +1,241 @@
+[**@isdk/ai-tool**](../README.md)
+
+***
+
+[@isdk/ai-tool](../globals.md) / IPubSubServerTransport
+
+# Interface: IPubSubServerTransport
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:71](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L71)
+
+Defines the interface for a server-side PubSub transport layer.
+
+This abstraction allows the `EventServer` to operate independently of the
+underlying real-time communication protocol (e.g., SSE, WebSockets, IPC).
+An implementation of this interface is responsible for managing client
+connections, subscriptions, and message passing.
+
+## Properties
+
+### mount()?
+
+> `optional` **mount**: (`path`, `options`?) => `void`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:89](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L89)
+
+Optional method to mount or register the transport's endpoint with an HTTP
+server or framework. This is typically required for protocols like SSE or
+WebSockets that need to handle incoming HTTP requests at a specific path.
+
+#### Parameters
+
+##### path
+
+`string`
+
+The URL path to handle (e.g., '/api/events').
+
+##### options?
+
+`Record`\<`string`, `any`\>
+
+Additional options for mounting, specific to the framework.
+
+#### Returns
+
+`void`
+
+***
+
+### name
+
+> `readonly` **name**: `string`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:75](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L75)
+
+A unique, human-readable name for the transport (e.g., 'sse', 'websocket').
+
+***
+
+### onConnection()
+
+> **onConnection**: (`cb`) => `void`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:144](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L144)
+
+Registers a callback to be invoked when a new client connection is established
+and a session is created.
+
+#### Parameters
+
+##### cb
+
+(`session`) => `void`
+
+The callback function that receives the new `PubSubServerSession`.
+
+#### Returns
+
+`void`
+
+***
+
+### onDisconnect()
+
+> **onDisconnect**: (`cb`) => `void`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:151](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L151)
+
+Registers a callback to be invoked when a client disconnects.
+
+#### Parameters
+
+##### cb
+
+(`session`) => `void`
+
+The callback function that receives the `PubSubServerSession` of the
+  disconnected client.
+
+#### Returns
+
+`void`
+
+***
+
+### onMessage()?
+
+> `optional` **onMessage**: (`cb`) => `void`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:159](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L159)
+
+Optional. Registers a callback to handle incoming messages from clients.
+This is only necessary for bidirectional transport protocols like WebSockets or IPC.
+
+#### Parameters
+
+##### cb
+
+(`session`, `event`, `data`, `ctx`?) => `void`
+
+The callback function that receives the session, event name, data, and context.
+
+#### Returns
+
+`void`
+
+***
+
+### protocol
+
+> `readonly` **protocol**: `string`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:79](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L79)
+
+The protocol identifier.
+
+***
+
+### publish()
+
+> **publish**: (`event`, `data`, `target`?, `ctx`?) => `void`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:132](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L132)
+
+Publishes an event from the server to connected clients.
+
+The transport implementation should handle broadcasting to all relevant
+clients or targeting specific clients based on the `target` parameter.
+
+#### Parameters
+
+##### event
+
+`string`
+
+The name of the event to publish.
+
+##### data
+
+`any`
+
+The payload for the event.
+
+##### target?
+
+Optional. Specifies the recipient(s) of the event.
+  If omitted, the event is typically broadcast to all subscribed clients.
+
+###### clientId?
+
+`string` \| `string`[]
+
+A single `PubSubClientId` or an array of IDs to
+  send the event to.
+
+##### ctx?
+
+[`PubSubCtx`](../type-aliases/PubSubCtx.md)
+
+Optional context for the PubSub operation.
+
+#### Returns
+
+`void`
+
+***
+
+### subscribe()
+
+> **subscribe**: (`events`?, `options`?) => [`PubSubClient`](PubSubClient.md)
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/pubsub/server.ts:107](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/pubsub/server.ts#L107)
+
+Establishes a connection with a client and subscribes it to an event stream.
+
+This method is designed to be generic. Transport-specific details, such as
+HTTP request/response objects or connection handles, should be passed
+inside the `options` parameter to avoid polluting the abstraction layer.
+
+#### Parameters
+
+##### events?
+
+`string`[]
+
+Optional array of event names to initially subscribe the client to.
+
+##### options?
+
+A container for transport-specific parameters.
+
+###### clientId?
+
+`string`
+
+An optional ID provided by the client. If not provided,
+  the transport should generate one.
+
+###### headers?
+
+`Record`\<`string`, `string`\>
+
+HTTP headers from the client request.
+
+###### req?
+
+`any`
+
+The underlying request object (e.g., `http.IncomingMessage`).
+
+###### res?
+
+`any`
+
+The underlying response object (e.g., `http.ServerResponse`).
+
+#### Returns
+
+[`PubSubClient`](PubSubClient.md)
+
+A `PubSubClient` object representing the newly connected client.

package/docs/api/interfaces/IReadTextFileChunksOptions.md

@@ -0,0 +1,143 @@
+[**@isdk/ai-tool**](../README.md)
+
+***
+
+[@isdk/ai-tool](../globals.md) / IReadTextFileChunksOptions
+
+# Interface: IReadTextFileChunksOptions
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/read-text-file-chunks.ts:5](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/read-text-file-chunks.ts#L5)
+
+## Extends
+
+- [`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md)
+
+## Properties
+
+### best?
+
+> `optional` **best**: `boolean`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:8](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L8)
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`best`](ITruncateToTokenLimitOptions.md#best)
+
+***
+
+### bySentence?
+
+> `optional` **bySentence**: `boolean`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:4](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L4)
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`bySentence`](ITruncateToTokenLimitOptions.md#bysentence)
+
+***
+
+### completeSentence?
+
+> `optional` **completeSentence**: `boolean`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:9](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L9)
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`completeSentence`](ITruncateToTokenLimitOptions.md#completesentence)
+
+***
+
+### corrected?
+
+> `optional` **corrected**: `boolean`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:10](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L10)
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`corrected`](ITruncateToTokenLimitOptions.md#corrected)
+
+***
+
+### countLLMTokens()?
+
+> `optional` **countLLMTokens**: (`text`, `modelId`?) => `Promise`\<`number`\>
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:12](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L12)
+
+#### Parameters
+
+##### text
+
+`string`
+
+##### modelId?
+
+`string`
+
+#### Returns
+
+`Promise`\<`number`\>
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`countLLMTokens`](ITruncateToTokenLimitOptions.md#countllmtokens)
+
+***
+
+### metaInfo?
+
+> `optional` **metaInfo**: `_RequireAtLeastOne`\<`Partial`\<[`IFileMetaInfo`](IFileMetaInfo.md)\>, `"size"`\>
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/read-text-file-chunks.ts:8](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/read-text-file-chunks.ts#L8)
+
+***
+
+### modelId?
+
+> `optional` **modelId**: `string`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/read-text-file-chunks.ts:7](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/read-text-file-chunks.ts#L7)
+
+#### Overrides
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`modelId`](ITruncateToTokenLimitOptions.md#modelid-2)
+
+***
+
+### sentences?
+
+> `optional` **sentences**: `string`[]
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:7](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L7)
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`sentences`](ITruncateToTokenLimitOptions.md#sentences)
+
+***
+
+### size?
+
+> `optional` **size**: `number`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/read-text-file-chunks.ts:6](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/read-text-file-chunks.ts#L6)
+
+#### Overrides
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`size`](ITruncateToTokenLimitOptions.md#size)
+
+***
+
+### truncLastSection?
+
+> `optional` **truncLastSection**: `boolean`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/utils/truncate-to-token-limit.ts:11](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/utils/truncate-to-token-limit.ts#L11)
+
+#### Inherited from
+
+[`ITruncateToTokenLimitOptions`](ITruncateToTokenLimitOptions.md).[`truncLastSection`](ITruncateToTokenLimitOptions.md#trunclastsection)

package/docs/api/interfaces/IServerToolTransport.md

@@ -0,0 +1,159 @@
+[**@isdk/ai-tool**](../README.md)
+
+***
+
+[@isdk/ai-tool](../globals.md) / IServerToolTransport
+
+# Interface: IServerToolTransport
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/server.ts:9](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/server.ts#L9)
+
+Defines the public interface for a server-side transport,
+responsible for exposing ServerTools to the network.
+
+## Extends
+
+- [`IToolTransport`](IToolTransport.md)
+
+## Indexable
+
+\[`name`: `string`\]: `any`
+
+## Properties
+
+### apiRoot
+
+> **apiRoot**: `string`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:22](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L22)
+
+The root endpoint for the remote service.
+For HTTP, this is a URL. For IPC, it could be a channel name.
+
+#### Inherited from
+
+[`IToolTransport`](IToolTransport.md).[`apiRoot`](IToolTransport.md#apiroot)
+
+***
+
+### options?
+
+> `optional` **options**: `any`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:26](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L26)
+
+Additional options for the transport start or fetch, passed by mount.
+
+#### Inherited from
+
+[`IToolTransport`](IToolTransport.md).[`options`](IToolTransport.md#options)
+
+***
+
+### Tools
+
+> **Tools**: *typeof* [`ToolFunc`](../classes/ToolFunc.md)
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:17](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L17)
+
+#### Inherited from
+
+[`IToolTransport`](IToolTransport.md).[`Tools`](IToolTransport.md#tools)
+
+## Methods
+
+### getRaw()?
+
+> `optional` **getRaw**(): `any`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/server.ts:34](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/server.ts#L34)
+
+Gets the underlying raw server instance.
+
+#### Returns
+
+`any`
+
+***
+
+### mount()
+
+> **mount**(`serverTools`, `apiPrefix`?, `options`?): `void`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/server.ts:16](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/server.ts#L16)
+
+Mounts the ServerTools registry, creating the necessary API routes.
+
+#### Parameters
+
+##### serverTools
+
+*typeof* [`ServerTools`](../classes/ServerTools.md)
+
+The ServerTools class.
+
+##### apiPrefix?
+
+`string`
+
+An optional prefix for all API routes.
+
+##### options?
+
+`any`
+
+Additional options for the transport start.
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+[`IToolTransport`](IToolTransport.md).[`mount`](IToolTransport.md#mount)
+
+***
+
+### start()
+
+> **start**(`options`?): `Promise`\<`any`\>
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/server.ts:22](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/server.ts#L22)
+
+Starts the transport layer, making it listen for incoming connections.
+
+#### Parameters
+
+##### options?
+
+`any`
+
+Protocol-specific options (e.g., { port, host }).
+
+#### Returns
+
+`Promise`\<`any`\>
+
+***
+
+### stop()
+
+> **stop**(`force`?): `Promise`\<`void`\>
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/server.ts:29](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/server.ts#L29)
+
+Stops the server instance gracefully.
+
+#### Parameters
+
+##### force?
+
+`boolean`
+
+Optional flag to force shutdown immediately
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Promise<void> when server is fully stopped

package/docs/api/interfaces/IToolTransport.md

@@ -0,0 +1,73 @@
+[**@isdk/ai-tool**](../README.md)
+
+***
+
+[@isdk/ai-tool](../globals.md) / IToolTransport
+
+# Interface: IToolTransport
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:16](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L16)
+
+## Extended by
+
+- [`IClientToolTransport`](IClientToolTransport.md)
+- [`IServerToolTransport`](IServerToolTransport.md)
+
+## Indexable
+
+\[`name`: `string`\]: `any`
+
+## Properties
+
+### apiRoot
+
+> **apiRoot**: `string`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:22](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L22)
+
+The root endpoint for the remote service.
+For HTTP, this is a URL. For IPC, it could be a channel name.
+
+***
+
+### options?
+
+> `optional` **options**: `any`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:26](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L26)
+
+Additional options for the transport start or fetch, passed by mount.
+
+***
+
+### Tools
+
+> **Tools**: *typeof* [`ToolFunc`](../classes/ToolFunc.md)
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:17](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L17)
+
+## Methods
+
+### mount()
+
+> **mount**(`Tools`, `apiRoot`?, `options`?): `any`
+
+Defined in: [@isdk/ai-tools/packages/ai-tool/src/transports/base.ts:28](https://github.com/isdk/ai-tool.js/blob/4ebf370aaec9c78535cb40ffc19656d7bddcb145/src/transports/base.ts#L28)
+
+#### Parameters
+
+##### Tools
+
+*typeof* [`ToolFunc`](../classes/ToolFunc.md)
+
+##### apiRoot?
+
+`string`
+
+##### options?
+
+`any`
+
+#### Returns
+
+`any`