@isdk/ai-tool 0.5.8 → 0.7.0

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`).

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

package/docs/api/_media/transport.md

@@ -0,0 +1,137 @@
+# ToolFunc: Client-Server Communication
+
+This guide provides a comprehensive overview of the `ai-tool` transport layer, a powerful system designed to facilitate communication between server-side functions and client-side applications. It enables seamless Remote Procedure Calls (RPC) by abstracting the underlying network protocol.
+
+This system is composed of two main parts:
+
+1. **Tools (`ServerTools`/`ClientTools`):** Classes that define the functions to be executed.
+2. **The Transport Layer:** The underlying bridge that handles network communication.
+
+**Prerequisite:** This document assumes you have a basic understanding of the `ToolFunc` framework. If not, please review the [`toolFunc.md`](./toolFunc.md) first.
+
+## 1. `ServerTools`: Defining Backend Functions
+
+`ServerTools` is the base class for any function you want to make available for remote clients. It extends `ToolFunc`, inheriting all its features, but is specifically designed to be discovered and executed via the transport layer.
+
+Think of a `ServerTools` instance as a single, network-addressable endpoint for a specific function.
+
+### Basic Example
+
+Here is the most basic example of defining a server tool. Note that at this stage, it's just a definition; it can't be reached by a client until a transport is set up.
+
+```typescript
+import { ServerTools } from '@isdk/ai-tool';
+
+// Define a tool that can be called remotely
+ServerTools.register({
+  name: 'getUserProfile',
+  description: 'Fetches a user profile by ID.',
+  params: { id: { type: 'string' } },
+  func: async ({ id }: { id: string }) => {
+    // In a real app, you'd fetch this from a database
+    return { id, name: 'Jane Doe', email: 'jane.doe@example.com' };
+  },
+});
+```
+
+## 2. The Transport Layer: Bridging Client and Server
+
+The transport layer's primary purpose is to **decouple your tool's business logic from the network protocol**. It acts as a bridge, allowing a client to execute a function on a server as if it were a local method.
+
+The transport layer makes `ServerTools` accessible over a network and allows `ClientTools` to call them.
+
+- **The Server Transport (`IServerToolServerTransport`)**
+  - Its job is to listen for incoming network requests (e.g., over HTTP).
+  - It finds the correct registered `ServerTools` instance by its name.
+  - It executes the tool and sends the result back in a response.
+
+- **The Client Transport (`IClientToolTransport`)**
+  - Its job is to connect to a server's `apiRoot`.
+  - It uses a `mount()` helper to fetch all available tool definitions from the server and automatically create local proxy `ClientTools` for them.
+
+### End-to-End Transport Example
+
+This example shows how to use the `Fastify` (server) and `HttpClient` (client) transports to bring the `getUserProfile` tool online.
+
+**Server-Side Setup:**
+
+```typescript
+// server.ts
+import { ServerTools, FastifyServerToolTransport } from '@isdk/ai-tool';
+
+// (Your ServerTools.register call from above)
+
+// 1. Create a server transport instance.
+const serverTransport = new FastifyServerToolTransport();
+
+// 2. Mount the ServerTools class. The transport finds all registered tools
+//    and exposes them under the '/api' prefix.
+serverTransport.mount(ServerTools, '/api');
+
+// 3. Start the server.
+serverTransport.start({ port: 3000 });
+```
+
+**Client-Side Setup:**
+
+```typescript
+// client.ts
+import { ClientTools, HttpClientToolTransport } from '@isdk/ai-tool';
+
+async function main() {
+  const apiRoot = 'http://localhost:3000/api';
+
+  // 1. Create a client transport pointing to the server.
+  const clientTransport = new HttpClientToolTransport(apiRoot);
+
+  // 2. Mount ClientTools. This crucial step connects to the server,
+  //    fetches the definitions for all available ServerTools (like 'getUserProfile'),
+  //    and creates the local ClientTools proxies.
+  await clientTransport.mount(ClientTools);
+
+  // 3. Get the proxy tool and run it as if it were local.
+  const getUserProfile = ClientTools.get('getUserProfile');
+  const profile = await getUserProfile.run({ id: '123' });
+
+  console.log(profile);
+}
+main();
+```
+
+## 3. Advanced Tool Types & Transport Interaction
+
+The framework provides specialized subclasses of `ServerTools` for common API patterns. A key concept is that the **transport layer remains agnostic** to these types. It always just finds a tool by its name and executes its main `func`. The tool itself is responsible for any internal logic, like routing to sub-methods.
+
+### `RpcMethodsServerTool`
+
+This class allows you to group multiple related functions into a single tool, like methods on a class.
+
+- **How it works:** You define methods in your class with a `$` prefix (e.g., `$add`, `$subtract`). The tool's main `func` acts as a dispatcher, using an `act` parameter from the client to call the correct internal method.
+- **Transport Interaction:** The transport is unaware of this. It just calls the main `func` of the `calculator` tool. The tool's internal dispatcher does the rest.
+
+**Example:**
+
+```typescript
+// tools/CalculatorTool.ts
+import { RpcMethodsServerTool } from '@isdk/ai-tool';
+
+export class CalculatorTool extends RpcMethodsServerTool {
+  $add({ a, b }: { a: number, b: number }) { return a + b; }
+  $subtract({ a, b }: { a: number, b: number }) { return a - b; }
+}
+
+// server.ts - You would register this tool:
+// new CalculatorTool('calculator').register();
+
+// client.ts - The client-side proxy would have .add() and .subtract() methods:
+// const sum = await calculator.add({ a: 10, b: 5 });
+```
+
+### `ResServerTools`
+
+This class extends `RpcMethodsServerTool` to provide a conventional, resource-oriented (CRUD) API.
+
+- **How it works:** It maps standard method names like `get`, `list`, `post`, `put`, and `delete` to different HTTP verbs and URL patterns.
+- **Transport Interaction:** Just like with `RpcMethodsServerTool`, the transport remains agnostic. For example, a `GET /api/myResource/123` request is routed by the `Fastify` transport to the `myResource` tool. The tool's internal logic then identifies the `GET` verb and the `id` parameter and calls its own `get()` method.
+
+This architecture provides a clean, powerful, and extensible way to build and consume APIs, clearly separating your business logic from the complexities of network communication.