From 8578e5e899275506ae31260257ad1cf2c397bdc2 Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Wed, 19 Jun 2024 17:58:02 +0200 Subject: [PATCH 01/11] chore: adjust readme.md for beginners Signed-off-by: Olivier Halupczok --- README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 7cd51b6..8001c72 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,11 @@ # 🤖 AI Assistant -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. +`@boldare/openai-assistant` - library to kickstart your AI Assistant development under 15 minutes. + +Introducing the NestJS library. Whether you're building a virtual assistant, or an interactive chatbot for engaging user experiences, our library empowers you to leverage cutting-edge AI capabilities with minimal effort. + +**The library provides ready-to-use API endpoints** handling your assistant and WebSocket server for real-time communication between the client and the assistant. Install the library and paste the config to get it running. ## 🚀 Features @@ -28,6 +32,8 @@ Introducing the NestJS library, designed to harness the power of OpenAI's Assist #### Additional features in the repository +The repository not only contains a library but also provides additional features. You don't have to build everything from scratch. You can just clone the repository and run it to take advantage of the features above and below: + - **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. @@ -35,13 +41,17 @@ Introducing the NestJS library, designed to harness the power of OpenAI's Assist 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: Prerequisites + -Install Node.js which includes Node Package Manager (`^20.0.0` version). +### Step 0: Prerequisites -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/). +- Node.js (`^20.0.0` version) +- npm (`^10.0.0` version) +- NestJS (`^10.0.0` version) +- OpenAI (`^4.51.0` version) +- OpenAI API key -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: +Open or create your NestJS application where you would like to integrate the AI Assistant. To create a new NestJS application, use the following command: ```bash nest new project-name @@ -49,7 +59,7 @@ nest new project-name ### Step 1: Installation -Install the library using npm: +Install the library and `openai` package using npm: ```bash npm i @boldare/openai-assistant openai --save @@ -71,38 +81,118 @@ Add the following content to the `.env` file: # OpenAI API Key OPENAI_API_KEY= -# Assistant ID - leave it empty if you don't have an assistant yet +# Assistant ID - leave it empty if you don't have an assistant to reuse ASSISTANT_ID= ``` -Please note that the `.env` file should not be committed to the repository. Add it to the `.gitignore` file to prevent it from being committed. +Please note that the `.env` file should not be committed to the repository. *Add the `.env` file to the `.gitignore`* file to prevent it from being committed. ### Step 3: Configuration The library provides a way to configure the assistant with the `AssistantModule.forRoot` method. The method takes a configuration object as an argument. Create a new configuration file like in a [sample configuration file (chat.config.ts)](apps%2Fapi%2Fsrc%2Fapp%2Fchat%2Fchat.config.ts) and fill it with the necessary configuration. -More details about the configuration with code examples can be found in the [wiki](https://github.com/boldare/openai-assistant/wiki/%F0%9F%A4%96-AI-Assistant#step-3-configuration). +```typescript +// chat.config.ts file +import { AssistantConfigParams } from '@boldare/openai-assistant'; +import { AssistantCreateParams } from 'openai/resources/beta'; + +// Default OpenAI configuration +export const assistantParams: AssistantCreateParams = { + name: 'Your assistant name', + instructions: `You are a chatbot assistant. Speak briefly and clearly.`, + tools: [ + { type: 'code_interpreter' }, + ], + model: 'gpt-4-turbo', + temperature: 0.05, +}; + +// Additional configuration for our assistant +export const assistantConfig: AssistantConfigParams = { + id: process.env['ASSISTANT_ID'], + params: assistantParams, + filesDir: './apps/api/src/app/knowledge', + toolResources: { + codeInterpreter: { + fileNames: [], + }, + }, +}; +``` + + +More details about the configuration can be found in the [wiki](https://github.com/boldare/openai-assistant/wiki/%F0%9F%A4%96-AI-Assistant#step-3-configuration). + +#### What is this step for? +From now you can run your application and call the assistant. ### Step 4: Function calling +Function calling allows you to extend the assistant's capabilities with custom logic. **If you are not going to use function calling you can jump to: [Step 5: Testing](#step-5-testing).** + Create a new service that extends the `AgentBase` class, fill the definition and implement the `output` method. -- The `output` method is the main method that will be called when the function is invoked. -- The `definition` property is an object that describes the function and its parameters. +- The `output` method is the main method that will be called when the function is invoked by the assistant. +- The `definition` property is an object that describes the function and its parameters so the assistant can understand how to call it. For more information about function calling, you can refer to the [OpenAI documentation](https://platform.openai.com/docs/assistants/tools/defining-functions). The instructions for creating a function can be found in the [wiki](https://github.com/boldare/openai-assistant/wiki/%F0%9F%A4%96-AI-Assistant#step-4-function-calling), while examples can be found in the [agents](apps/api/src/app/chat/agents) directory. +#### What is this step for? + +If you've defined a function and the output method, you can now call it from the assistant just by asking him to do the action described in the function definition. + + +### Step 5: Running the application and testing + +Run your application and this will allow you to test the assistant. + + ```bash + # use this if you are using the repository: + npm run start:dev + + # if you are using NestJS please check the npm scripts in the package.json file + # defualt command for NestJS is: + npm run start + ``` + + Then you can test the assistant. + 1. First, you need to create a thread. You can create one + by sending a POST request to the `/assistant/threads` endpoint with the empty body: + ``` + {} + ``` + 2. Then you can send a message to the assistant by sending a POST request to the `/assistant/chat` endpoint with the following body. + ```json + { + "threadId": "your-thread-id", + "content": "Hello, how are you?" + } + ``` + --- -# 👨‍💻 Repository +## 👨‍💻 Repository The complete documentation on how to run the demo with all applications and libraries from the repository can be found in the [wiki](https://github.com/boldare/openai-assistant/wiki/%F0%9F%91%A8%E2%80%8D%F0%9F%92%BB-Repository). +## Are you stuck? + +Boldare's engineers are here to help you. If you have any questions or need help with the implementation, feel free to **[click here to book a call with one of our engineers.](https://calendly.com/olivier-halupczok/30min)** + +You can also ask questions in the [GitHub Discussions](https://github.com/boldare/openai-assistant/discussions) section. + +**Learn more how Boldare can help you with [AI development on our website](https://www.boldare.com/services/ai-software-development-consulting/).** + + + + + + --- # License -`@boldare/openai-assistant` is MIT licensed +`@boldare/openai-assistant` and this repository is MIT licensed From 8b15d4098b6d3fa867258384807205803c71c6cf Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Wed, 19 Jun 2024 20:53:23 +0200 Subject: [PATCH 02/11] chore: change the order --- README.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 8001c72..90ca8cb 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,11 @@

- demo 🔹 - api docs 🔹 + Demo 🔹 + API docs 🔹 npm 🔹 - github + Github 🔹 + How we can help you

# 🤖 AI Assistant @@ -21,7 +22,7 @@ Introducing the NestJS library. Whether you're building a virtual assistant, or ## 🚀 Features -#### AI Assistant library features +### AI Assistant library features - **Function calling**: The library provides a way to create functions, which allows you to extend the assistant's capabilities with custom logic. - **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. @@ -174,25 +175,23 @@ Run your application and this will allow you to test the assistant. --- -## 👨‍💻 Repository - -The complete documentation on how to run the demo with all applications and libraries from the repository can be found in the [wiki](https://github.com/boldare/openai-assistant/wiki/%F0%9F%91%A8%E2%80%8D%F0%9F%92%BB-Repository). -## Are you stuck? +## 🤔 Are you stuck? Boldare's engineers are here to help you. If you have any questions or need help with the implementation, feel free to **[click here to book a call with one of our engineers.](https://calendly.com/olivier-halupczok/30min)** -You can also ask questions in the [GitHub Discussions](https://github.com/boldare/openai-assistant/discussions) section. - -**Learn more how Boldare can help you with [AI development on our website](https://www.boldare.com/services/ai-software-development-consulting/).** +**Learn more how [Boldare can help you with AI development on our website](https://www.boldare.com/services/ai-software-development-consulting/).** +You can also ask questions in the [GitHub Discussions](https://github.com/boldare/openai-assistant/discussions) section. +--- +## 👨‍💻 Repository - +The complete documentation on how to run the demo with all applications and libraries from the repository can be found in the [wiki](https://github.com/boldare/openai-assistant/wiki/%F0%9F%91%A8%E2%80%8D%F0%9F%92%BB-Repository). --- -# License +## License `@boldare/openai-assistant` and this repository is MIT licensed From 295f805edcf4c612833e0f01cb4f06d3881de81d Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Wed, 19 Jun 2024 21:03:10 +0200 Subject: [PATCH 03/11] chore: new section --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 90ca8cb..7247f87 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,15 @@ The complete documentation on how to run the demo with all applications and libr --- +## Contributions + +Would you like to see new features in the library? +- You can freely contribute to the project! Just create a pull request with your changes. +- [Talk your idea over with one of our engineers.](https://calendly.com/olivier-halupczok/30min) +- You can also [post your idea here](https://github.com/boldare/openai-assistant/discussions). + +--- + ## License `@boldare/openai-assistant` and this repository is MIT licensed From 43900e3827b8b5e4a5b56d0db749aad7e4f50585 Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Thu, 20 Jun 2024 10:44:52 +0200 Subject: [PATCH 04/11] chore: change the config example in the so it contains file search --- README.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 7247f87..9e58375 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,7 @@ import { AssistantCreateParams } from 'openai/resources/beta'; export const assistantParams: AssistantCreateParams = { name: 'Your assistant name', instructions: `You are a chatbot assistant. Speak briefly and clearly.`, - tools: [ - { type: 'code_interpreter' }, - ], + tools: [{ type: 'file_search'}], model: 'gpt-4-turbo', temperature: 0.05, }; @@ -114,8 +112,14 @@ export const assistantConfig: AssistantConfigParams = { params: assistantParams, filesDir: './apps/api/src/app/knowledge', toolResources: { - codeInterpreter: { - fileNames: [], + file_search: { + // Provide files if you use file_search tool + files: [ + { + name: 'example', + content: 'This is an example file.', + }, + ], }, }, }; From 3f17a111331473c2d4570605117013a724abd0a2 Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Thu, 20 Jun 2024 10:45:20 +0200 Subject: [PATCH 05/11] fix: fix the anchor in the readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9e58375..329f12f 100644 --- a/README.md +++ b/README.md @@ -134,7 +134,7 @@ From now you can run your application and call the assistant. ### Step 4: Function calling -Function calling allows you to extend the assistant's capabilities with custom logic. **If you are not going to use function calling you can jump to: [Step 5: Testing](#step-5-testing).** +Function calling allows you to extend the assistant's capabilities with custom logic. **If you are not going to use function calling you can jump to: [Step 5: Testing](#step-5-running-the-application-and-testing).** Create a new service that extends the `AgentBase` class, fill the definition and implement the `output` method. From 511043837e33da2cf7855a57e6ab98f82ebd00d8 Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Thu, 20 Jun 2024 10:46:02 +0200 Subject: [PATCH 06/11] chore: improve wording and structure --- README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 329f12f..34d262e 100644 --- a/README.md +++ b/README.md @@ -158,18 +158,15 @@ Run your application and this will allow you to test the assistant. # use this if you are using the repository: npm run start:dev - # if you are using NestJS please check the npm scripts in the package.json file + # if you are using your own NestJS application, please check the npm scripts in the package.json file # defualt command for NestJS is: npm run start ``` Then you can test the assistant. 1. First, you need to create a thread. You can create one - by sending a POST request to the `/assistant/threads` endpoint with the empty body: - ``` - {} - ``` - 2. Then you can send a message to the assistant by sending a POST request to the `/assistant/chat` endpoint with the following body. + by sending a POST request to the `/assistant/threads` endpoint with the **empty body**. + 2. Then you can send a message to the assistant by sending a POST request to the `/assistant/chat` endpoint with the following body: ```json { "threadId": "your-thread-id", From 0c200718e6253db571546b43eb577c36551f6fbd Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Thu, 20 Jun 2024 11:54:48 +0200 Subject: [PATCH 07/11] chore: simplify readme --- README.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 34d262e..263b3ec 100644 --- a/README.md +++ b/README.md @@ -24,19 +24,20 @@ Introducing the NestJS library. Whether you're building a virtual assistant, or ### AI Assistant library features -- **Function calling**: The library provides a way to create functions, which allows you to extend the assistant's capabilities with custom logic. -- **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. -- **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. -- **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**: create functions, so assistant can execute your custom logic! +- **TTS (Text-to-Speech)**: convert text to speech, so you can hear your assistant! +- **STT (Speech-to-Text)**: convert speech to text, so you can make conversation easier! +- **File support**: add files to the assistant, so you can extend assistant's knowledge base with custom data! +- **WebSockets**: establish WebSocket server for real-time communication between the client and the assistant! +- **REST API**: Just use ready REST API for communication with the assistant! +- **Vision with GPT-4o** - use the GPT-4o and make your assistant understand images and generate text based on them! #### Additional features in the repository -The repository not only contains a library but also provides additional features. You don't have to build everything from scratch. You can just clone the repository and run it to take advantage of the features above and below: +The repository contains a library but also provides additional features. You can just clone the repository and use it instantly to gain from all features: -- **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. +- **Embedded chatbot**: embed the chatbot on various websites through JavaScript scripts! +- **Chatbot client application**: use ready client application (SPA) with a chatbot! ## 🏆 Getting started @@ -58,14 +59,19 @@ Open or create your NestJS application where you would like to integrate the AI nest new project-name ``` +Now you have to install the packages. Go to the next step. + ### Step 1: Installation +Make sure you are in the root directory of your project. Install the library and `openai` package using npm: ```bash npm i @boldare/openai-assistant openai --save ``` +The library is installed but we have to configure it. Go to the next step. + ### Step 2: Env variables Set up your environment variables, create environment variables in the `.env` file in the root directory of the project, and populate it with the necessary secrets. The assistant ID is optional and serves as a unique identifier for your assistant. When the environment variable is not set, the assistant will be created automatically. You can use the assistant ID to connect to an existing assistant, which can be found in the OpenAI platform after creating an assistant. @@ -88,6 +94,8 @@ ASSISTANT_ID= Please note that the `.env` file should not be committed to the repository. *Add the `.env` file to the `.gitignore`* file to prevent it from being committed. +This was the first step needed to run the library. The next step is to configure the assistant. + ### Step 3: Configuration The library provides a way to configure the assistant with the `AssistantModule.forRoot` method. The method takes a configuration object as an argument. Create a new configuration file like in a [sample configuration file (chat.config.ts)](apps%2Fapi%2Fsrc%2Fapp%2Fchat%2Fchat.config.ts) and fill it with the necessary configuration. From c718edec57c588280ecef58c162a175a7f2c678c Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Thu, 20 Jun 2024 11:57:20 +0200 Subject: [PATCH 08/11] fix: fix exemplary snippet code --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index 263b3ec..ef07ba1 100644 --- a/README.md +++ b/README.md @@ -122,12 +122,7 @@ export const assistantConfig: AssistantConfigParams = { toolResources: { file_search: { // Provide files if you use file_search tool - files: [ - { - name: 'example', - content: 'This is an example file.', - }, - ], + fileNames: ['example1.txt', 'example2.txt'], }, }, }; From 0183adea113de19e894c0a92e2fc8c5821680eae Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Thu, 20 Jun 2024 13:14:32 +0200 Subject: [PATCH 09/11] chore: clarify readme.md --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ef07ba1..a1ac7f5 100644 --- a/README.md +++ b/README.md @@ -168,7 +168,7 @@ Run your application and this will allow you to test the assistant. Then you can test the assistant. 1. First, you need to create a thread. You can create one - by sending a POST request to the `/assistant/threads` endpoint with the **empty body**. + by sending a POST request to the `/assistant/threads` endpoint with the **empty object in the body**. 2. Then you can send a message to the assistant by sending a POST request to the `/assistant/chat` endpoint with the following body: ```json { @@ -176,6 +176,9 @@ Run your application and this will allow you to test the assistant. "content": "Hello, how are you?" } ``` + 3. The assistant will respond with a message. You can send more messages to the assistant by sending a POST request to the `/assistant/chat` endpoint with the same body as in step 2. + + Congrats! You have successfully integrated the AI Assistant library into your NestJS application. 🎉 --- From 2ef6d1a2dcc5c5aad69ffc56d31facb6deb02e46 Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Fri, 21 Jun 2024 11:08:25 +0200 Subject: [PATCH 10/11] feat: add tutorial to the readme.md --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a1ac7f5..10a8fd1 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,18 @@ How we can help you

-# 🤖 AI Assistant +# 🤖 AI Assistant `@boldare/openai-assistant` - library to kickstart your AI Assistant development under 15 minutes. Introducing the NestJS library. Whether you're building a virtual assistant, or an interactive chatbot for engaging user experiences, our library empowers you to leverage cutting-edge AI capabilities with minimal effort. **The library provides ready-to-use API endpoints** handling your assistant and WebSocket server for real-time communication between the client and the assistant. Install the library and paste the config to get it running. +## 📚 Watch the tutorial + + + ## 🚀 Features ### AI Assistant library features From c9270f49c7286c8d92ea7156e5017cc707ed9059 Mon Sep 17 00:00:00 2001 From: Olivier Halupczok Date: Fri, 21 Jun 2024 11:26:09 +0200 Subject: [PATCH 11/11] fix: fix youtube video --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10a8fd1..45e7a82 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Introducing the NestJS library. Whether you're building a virtual assistant, or ## 📚 Watch the tutorial - +[![Watch the tutorial](https://img.youtube.com/vi/rxPdFat90qY/0.jpg)](https://www.youtube.com/watch?v=rxPdFat90qY) ## 🚀 Features