@agentica/rpc 0.10.1 → 0.10.3

package/README.md

@@ -38,17 +38,21 @@ await driver.conversate("Hello, what you can do?");
 ## How to use
 ### Setup
 ```bash
-npm install @agentica/core @agentica/rpc @samchon/openapi typia tgrid
+# SERVER APPLICATION
+npm install @agentica/core @agentica/rpc @samchon/openapi tgrid typia
 npx typia setup
+
+# CLIENT APPLICATION
+npm install @agentica/core @agentica/rpc @samchon/openapi tgrid
 ```
 
 Install `@agentica/rpc` with its dependent libraries.
 
-Note that, you have to install not only `@agentica/core` and `@agentica/rpc`, but also [`@samchon/openapi`](https://github.com/samchon/openapi), [`typia`](https://github.com/samchon/typia) and [`tgrid`](https://github.com/samchon/tgrid) too.
+Note that, you have to install not only `@agentica/core` and `@agentica/rpc`, but also [`@samchon/openapi`](https://github.com/samchon/openapi) and [`tgrid`](https://github.com/samchon/tgrid) too. If you're developing server application, you have to install `typia` too.
 
 `@samchon/openapi` is an OpenAPI specification library which can convert Swagger/OpenAPI document to LLM function calling schema. And `typia` is a transformer (compiler) library which can compose LLM function calling schema from a TypeScript class type. And then `tgrid` is an RPC (REmote Procedure Call) framework supporting the websocket protocol.
 
-By the way, as `typia` is a transformer library analyzing TypeScript source code in the compilation level, it needs additional setup command `npx typia setup`. Also, if your client (frontend) application is not using the standard TypeScript compiler (not `tsc`), you have to setup [`@ryoppippi/unplugin-typia`](https://typia.io/docs/setup/#unplugin-typia) too.
+By the way, as `typia` is a transformer library analyzing TypeScript source code in the compilation level, it needs additional setup command `npx typia setup` when developing server application. Also, if your client (frontend) application is not using the standard TypeScript compiler (not `tsc`), you have to setup [`@ryoppippi/unplugin-typia`](https://typia.io/docs/setup/#unplugin-typia) too.
 
 ### Server Application
 ```typescript
@@ -111,6 +115,110 @@ And then call the backend server's function `IAgenticaRpcService.conversate()` r
 
 
 
+## NestJS Application
+### Bootstrap
+```bash
+npx nestia start <directory>
+cd <directory>
+npm install @agentica/core @agentica/rpc @samchon/openapi tgrid
+```
+
+You can integrate `@agentica` with [NestJS Framework](https://nestjs.com) utilizing [Nestia](https://nestia.io).
+
+At first, create a boilerplate project of NestJS combined with Nestia by running `npx nesta start` command. And then install `@agentica/rpc` with its dependency packages.
+
+```typescript
+import { WebSocketAdaptor } from "@nestia/core";
+import { INestApplication } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+
+import { MyConfiguration } from "./MyConfiguration";
+import { MyModule } from "./MyModule";
+
+export class MyBackend {
+  private application_?: INestApplication;
+
+  public async open(): Promise<void> {
+    //----
+    // OPEN THE BACKEND SERVER
+    //----
+    // MOUNT CONTROLLERS
+    this.application_ = await NestFactory.create(MyModule, { logger: false });
+    WebSocketAdaptor.upgrade(this.application_);
+    ...
+  }
+}
+```
+
+After setup, update `src/MyBackend.ts` file to call `WebSocketAdaptor.upgrade()` function to the NestJS application instance. The function `WebSocketAdaptor.upgrade()` will make the NestJS backend server to compatible with WebSocket protocol.
+
+### API Controller
+```typescript
+import { AgenticaRpcService, IAgenticaRpcListener } from "@agentica/rpc";
+import { WebSocketRoute } from "@nestia/core";
+import { Controller } from "@nestjs/common";
+import { WebSocketAcceptor } from "tgrid";
+
+@Controller("chat")
+export class ChatController {
+  @WebSocketRoute()
+  public async start(
+    // @WebSocketRoute.Param("id") id: string,
+    @WebSocketRoute.Acceptor()
+    acceptor: WebSocketAcceptor<
+      null, // header
+      AgenticaRpcService,
+      IAgenticaRpcListener
+    >,
+  ): Promise<void> {
+    await acceptor.accept(
+      new AgenticaRpcService({
+        agent: new Agentica({ ... }),
+        listener: acceptor.getDriver(),
+      }),
+    );
+  }
+}
+```
+
+Make a new NestJS controller class like above. 
+
+When a client connects to the server with `ws://localhost:3001/chat` URL, Agentica made chatbot would be started in the WebSocket protocol.
+
+If you need path or query parameters, utilize `@WebSocketRoute.Path()` or `@WebSocketRoute.Query()` decorator functions.
+
+### Software Development Kit
+```bash
+npx nestia sdk
+```
+
+When backend server development has been completed, you can generate SDK (Software Development Kit) library for client developers by running `npx nestia sdk` command.
+
+Client developers can utilize the SDK library like below.
+
+```typescript
+import { IAgenticaRpcListener } from "@agentica/rpc";
+import api from "@ORGANIZATION/PROJECT-api";
+
+const { connector, driver } = await api.functional.chat.start(
+  {
+    host: "http://localhost:3000",
+  } satisfies api.IConnection,
+  {
+    text: async (evt) => {
+      console.log(evt.role, evt.text);
+    },
+    describe: async (evt) => {
+      console.log("describer", evt.text);
+    },
+  } satisfies IAgenticaRpcListener,
+);
+await driver.conversate("Hello, what you can do?");s
+```
+
+
+
+
 ## Principles
 ### Remote Procedure Call
 ```mermaid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentica/rpc",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "main": "lib/index.js",
   "description": "Agentic AI Library specialized in LLM Function Calling",
   "scripts": {
@@ -37,7 +37,7 @@
     "src"
   ],
   "dependencies": {
-    "@agentica/core": "^0.10.1",
+    "@agentica/core": "^0.10.3",
     "@samchon/openapi": "^3.0.0",
     "@samchon/shopping-api": "^0.15.0",
     "chalk": "4.1.2",