From af6ad6f44031936fc26d91cd4ecf527600d3f58d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Musia=C5=82?= Date: Wed, 13 Mar 2024 15:11:51 +0100 Subject: [PATCH] doc: readme update (#31) --- README.md | 70 ++++++++++++++---- apps/api/src/app/chat/chat.module.ts | 2 +- .../app/modules/+chat/shared/chat.service.ts | 2 +- apps/spa/src/assets/boldare-circle.png | Bin 0 -> 6225 bytes apps/spa/src/environments/environment.ts | 6 +- .../src/environments/environment.prod.ts | 2 +- 6 files changed, 62 insertions(+), 20 deletions(-) create mode 100644 apps/spa/src/assets/boldare-circle.png diff --git a/README.md b/README.md index d806f76..132f63b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@

- Boldare + Boldare + +

+ +

+ + NPM

@@ -8,6 +14,24 @@ Introducing the NestJS library, designed to harness the power of OpenAI's Assistant, enabling developers to create highly efficient, scalable, and rapid AI assistants and chatbots. This library is tailored for seamless integration into the NestJS ecosystem, offering an intuitive API, WebSockets, and tools that streamline the development of AI-driven interactions. Whether you're building a customer service bot, a virtual assistant, or an interactive chatbot for engaging user experiences, our library empowers you to leverage cutting-edge AI capabilities with minimal effort. +## 🚀 Features + +#### AI Assistant library features +- **WebSockets**: The library provides a WebSocket server for real-time communication between the client and the assistant. +- **REST API**: The library provides a REST API for communication with the assistant. +- **Function calling**: The library provides a way to create functions, which allows you to extend the assistant's capabilities with custom logic. +- **File support**: The library provides a way to add files to the assistant, which allows you to extend the assistant's knowledge base with custom data. +- **TTS (Text-to-Speech)**: The library provides a way to convert text to speech, which allows you to create voice-based interactions with the assistant. +- **STT (Speech-to-Text)**: The library provides a way to convert speech to text, which allows you to create voice-based interactions with the assistant. + +#### Additional features in the repository +- **Embedded chatbot**: The library provides a way to embed the chatbot on various websites through JavaScript scripts. +- **Chatbot client application**: The repository includes an example client application (SPA) with a chatbot. + +## Getting started + +In this section, you will learn how to integrate the AI Assistant library into your NestJS application. The following steps will guide you through the process of setting up the library and creating simple functionalities. + ### Step 0: Prerequiring Before you start, you will need to have an account on the OpenAI platform and an API key. You can create an account [here](https://platform.openai.com/). @@ -15,7 +39,7 @@ Before you start, you will need to have an account on the OpenAI platform and an Open or create your NestJS application where you would like to integrate the AI Assistant. If you don't have a NestJS application yet, you can create one using the following command: ```bash -$ nest new project-name +nest new project-name ``` ### Step 1: Installation @@ -23,7 +47,7 @@ $ nest new project-name Install the library using npm: ```bash -$ npm i @boldare/ai-assistant --save +npm i @boldare/ai-assistant --save ``` ### Step 2: Env variables @@ -33,7 +57,7 @@ Set up your environment variables, create environment variables in the `.env` fi Create a `.env` file in the root directory of your project and populate it with the necessary secrets: ```bash -$ touch .env +touch .env ``` Add the following content to the `.env` file: @@ -84,6 +108,18 @@ Import the AI Assistant module with your configuration into the module file wher export class ChatbotModule {} ``` +Automatically, the library will add WebSockets ([chat.gateway.ts](libs/ai-assistant/src/lib/chat/chat.gateway.ts)) and a [REST API](https://assistant.ai.boldare.dev/api/docs) for the assistant. The WebSocket server will be available at the `/` endpoint, and the [REST API](https://assistant.ai.boldare.dev/api/docs) will be available at the `/api` endpoint (depending on the API prefix). + +#### Websockets events + +Currently, the library provides the following WebSocket events: + +| Event name | Description | +|--------------------|----------------------------------------------------------| +| `send_message` | The event is emitted when the user sends a message. | +| `message_received` | The event is emitted when the assistant sends a message. | + + ### Step 4: Function calling Create a new service that extends the `AgentBase` class, fill the definition and implement the `output` method. @@ -124,6 +160,8 @@ export class GetNicknameAgent extends AgentBase { } ``` +More examples can be found in the [agents](apps/api/src/app/chat/agents) directory. + Import the service into the module file where you intend to use it: ```js @@ -168,7 +206,7 @@ The repository includes a library with an AI assistant as well as other useful p ### Step 1: Install dependencies ```bash -$ npm install +npm install ``` ### Step 2: Env variables @@ -176,28 +214,32 @@ $ npm install Set up your environment variables, copy the `.env.dist` file to `.env` file in the root directory of the project, and populate it with the necessary secrets. ```bash -$ cp .env.dist .env +cp .env.dist .env ``` ### Step 3: Run applications ```bash # Start the app (api and spa) -$ npm run start:dev +npm run start:dev # Start the api -$ npm run start:api +npm run start:api # Start the spa -$ npm run start:spa +npm run start:spa ``` Now you can open your browser and navigate to: -| URL | Description | -| ------------------------------ | --------------------------- | -| http://localhost:4200/ | Client application (SPA) | -| http://localhost:3000/api/ | API application | -| http://localhost:3000/api/docs | API documentation (swagger) | +| URL | Description | +|--------------------------------|-----------------------------------------| +| http://localhost:4200/ | Client application (Angular) | +| http://localhost:3000/ | API application, WebSockets (socket.io) | +| http://localhost:3000/api/ | API endpoints | +| http://localhost:3000/api/docs | API documentation (swagger) | ### 🎉 Happy coding 🎉 + +# License +`@boldare/ai-assistant` is MIT licensed diff --git a/apps/api/src/app/chat/chat.module.ts b/apps/api/src/app/chat/chat.module.ts index 89d637f..512a1d7 100644 --- a/apps/api/src/app/chat/chat.module.ts +++ b/apps/api/src/app/chat/chat.module.ts @@ -4,6 +4,6 @@ import { assistantConfig } from './chat.config'; import { AgentsModule } from './agents/agents.module'; @Module({ - imports: [AssistantModule.forRoot(assistantConfig), AgentsModule], + imports: [AgentsModule, AssistantModule.forRoot(assistantConfig)], }) export class ChatModule {} diff --git a/apps/spa/src/app/modules/+chat/shared/chat.service.ts b/apps/spa/src/app/modules/+chat/shared/chat.service.ts index 1c72ec4..24a6ea4 100644 --- a/apps/spa/src/app/modules/+chat/shared/chat.service.ts +++ b/apps/spa/src/app/modules/+chat/shared/chat.service.ts @@ -46,7 +46,7 @@ export class ChatService { } isTextMessage(message: ThreadMessage): boolean { - return message.content[0].type === 'text'; + return message.content?.[0]?.type === 'text'; } parseMessages(thread: GetThreadResponseDto): Message[] { diff --git a/apps/spa/src/assets/boldare-circle.png b/apps/spa/src/assets/boldare-circle.png new file mode 100644 index 0000000000000000000000000000000000000000..2f57dd7ffbd137e3587922d63084d2a6f78c319f GIT binary patch literal 6225 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