Skip to content

Commit 551929b

Browse files
sebastianmusialsebastianmusial
committed
chore: readme update
1 parent 2e95683 commit 551929b

File tree

1 file changed

+156
-40
lines changed

1 file changed

+156
-40
lines changed

‎README.md‎

Lines changed: 156 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,92 @@
1-
<p align="center">
1+
<div align="center" style="text-align: center;">
22
<a href="https://www.boldare.com/services/ai-software-development-consulting/" target="blank">
33
<img src="https://assistant.ai.boldare.dev/assets/ai-assistant.jpg" width="280" alt="Boldare" />
4-
</a>
5-
</p>
4+
</a><br><br>
65

7-
<p align="center">
8-
<a href="https://assistant.ai.boldare.dev/" target="_blank">demo</a> 🔹
9-
<a href="https://assistant.ai.boldare.dev/api/docs" target="_blank">api docs</a> 🔹
10-
<a href="https://www.npmjs.com/package/@boldare/openai-assistant" target="_blank">npm</a> 🔹
11-
<a href="https://github.com/boldare/openai-assistant" target="_blank">github</a>
12-
</p>
6+
A NestJS library for building efficient, scalable, and fast solutions using the OpenAI Assistant API (chatbots). <br> Kickstart your AI Assistant development in under 15 minutes 🚀
137

14-
[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/boldare/openai-assistant/tree/feat/heroku-deploy-btn)
8+
<a href="https://assistant.ai.boldare.dev/" target="_blank"><img alt="demo" src="https://img.shields.io/badge/demo-👀-green"></a>&nbsp;
9+
<a href="https://assistant.ai.boldare.dev/api/docs" target="_blank"><img alt="docs" src="https://img.shields.io/badge/api docs-📚-orange"></a>&nbsp;
10+
<a href="https://www.npmjs.com/package/@boldare/openai-assistant" target="_blank"><img alt="npm" src="https://img.shields.io/npm/v/%40boldare%2Fopenai-assistant"></a>&nbsp;
11+
<a href="https://www.boldare.com/services/ai-software-development-consulting/" target="_blank"><img alt="docs" src="https://img.shields.io/badge/How we can help you-💡-brown"></a>&nbsp;
12+
<a href="https://github.com/boldare/openai-assistant" target="_blank"><img alt="Github" src="https://img.shields.io/github/stars/boldare/openai-assistant"></a>
13+
14+
[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/boldare/openai-assistant)
1515

16+
</div>
1617

17-
# 🤖 AI Assistant
18+
# AI Assistant
1819

19-
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.
20+
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.
21+
22+
**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.
23+
24+
## 📚 Watch the tutorial
25+
26+
<div align="center" style="text-align: center;">
27+
28+
[![Watch the tutorial](https://img.youtube.com/vi/rxPdFat90qY/0.jpg)](https://www.youtube.com/watch?v=rxPdFat90qY)
29+
</div>
2030

2131
## 🚀 Features
2232

23-
#### AI Assistant library features
33+
### AI Assistant library features
2434

25-
- **Function calling**: The library provides a way to create functions, which allows you to extend the assistant's capabilities with custom logic.
26-
- **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.
27-
- **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.
28-
- **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.
29-
- **WebSockets**: The library provides a WebSocket server for real-time communication between the client and the assistant.
30-
- **REST API**: The library provides a REST API for communication with the assistant.
35+
- **Function calling**: create functions, so assistant can execute your custom logic!
36+
- **TTS (Text-to-Speech)**: convert text to speech, so you can hear your assistant!
37+
- **STT (Speech-to-Text)**: convert speech to text, so you can make conversation easier!
38+
- **File support**: add files to the assistant, so you can extend assistant's knowledge base with custom data!
39+
- **WebSockets**: establish WebSocket server for real-time communication between the client and the assistant!
40+
- **REST API**: Just use ready REST API for communication with the assistant!
41+
- **Vision with GPT-4o** - use the GPT-4o and make your assistant understand images and generate text based on them!
3142

3243
#### Additional features in the repository
3344

34-
- **Embedded chatbot**: The library provides a way to embed the chatbot on various websites through JavaScript scripts.
35-
- **Chatbot client application**: The repository includes an example client application (SPA) with a chatbot.
45+
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:
46+
47+
- **Embedded chatbot**: embed the chatbot on various websites through JavaScript scripts!
48+
- **Chatbot client application**: use ready client application (SPA) with a chatbot!
3649

3750
## 🏆 Getting started
3851

3952
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.
4053

41-
### Step 0: Prerequisites
54+
<!-- The information that after this steps we will have the endpoints ready -->
4255

43-
Install Node.js which includes Node Package Manager (`^20.0.0` version).
56+
</details>
57+
<details>
58+
<summary><b>Step 0:</b> Prerequisites</summary><br>
4459

45-
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/).
60+
- Node.js (`^20.0.0` version)
61+
- npm (`^10.0.0` version)
62+
- NestJS (`^10.0.0` version)
63+
- OpenAI (`^4.51.0` version)
64+
- OpenAI API key
4665

47-
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:
66+
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:
4867

4968
```bash
5069
nest new project-name
5170
```
5271

53-
### Step 1: Installation
72+
Now you have to install the packages. Go to the next step.
73+
74+
</details>
75+
<details>
76+
<summary><b>Step 1:</b> Installation</summary><br>
5477

55-
Install the library using npm:
78+
Make sure you are in the root directory of your project.
79+
Install the library and `openai` package using npm:
5680

5781
```bash
5882
npm i @boldare/openai-assistant openai --save
5983
```
6084

61-
### Step 2: Env variables
85+
The library is installed but we have to configure it. Go to the next step.
86+
87+
</details>
88+
<details>
89+
<summary><b>Step 2:</b> Env variables</summary><br>
6290

6391
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.
6492

@@ -74,38 +102,126 @@ Add the following content to the `.env` file:
74102
# OpenAI API Key
75103
OPENAI_API_KEY=
76104
77-
# Assistant ID - leave it empty if you don't have an assistant yet
105+
# Assistant ID - leave it empty if you don't have an assistant to reuse
78106
ASSISTANT_ID=
79107
```
80108

81-
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.
109+
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.
82110

83-
### Step 3: Configuration
111+
This was the first step needed to run the library. The next step is to configure the assistant.
112+
113+
</details>
114+
<details>
115+
<summary><b>Step 3:</b> Configuration</summary><br>
84116

85117
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.
86118

87-
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).
119+
```typescript
120+
// chat.config.ts file
121+
import { AssistantConfigParams } from '@boldare/openai-assistant';
122+
import { AssistantCreateParams } from 'openai/resources/beta';
123+
124+
// Default OpenAI configuration
125+
export const assistantParams: AssistantCreateParams = {
126+
name: 'Your assistant name',
127+
instructions: `You are a chatbot assistant. Speak briefly and clearly.`,
128+
tools: [{ type: 'file_search'}],
129+
model: 'gpt-4-turbo',
130+
temperature: 0.05,
131+
};
132+
133+
// Additional configuration for our assistant
134+
export const assistantConfig: AssistantConfigParams = {
135+
id: process.env['ASSISTANT_ID'],
136+
params: assistantParams,
137+
filesDir: './apps/api/src/app/knowledge',
138+
toolResources: {
139+
file_search: {
140+
// Provide files if you use file_search tool
141+
fileNames: ['example1.txt', 'example2.txt'],
142+
},
143+
},
144+
};
145+
```
146+
147+
148+
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).
149+
150+
#### What is this step for?
151+
From now you can run your application and call the assistant.
152+
153+
154+
</details>
155+
<details>
156+
<summary><b>Step 4:</b> Function calling</summary><br>
88157

158+
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).**
89159

90-
### Step 4: Function calling
160+
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).**
91161

92162
Create a new service that extends the `AgentBase` class, fill the definition and implement the `output` method.
93163

94-
- The `output` method is the main method that will be called when the function is invoked.
95-
- The `definition` property is an object that describes the function and its parameters.
164+
- The `output` method is the main method that will be called when the function is invoked by the assistant.
165+
- The `definition` property is an object that describes the function and its parameters so the assistant can understand how to call it.
96166

97167
For more information about function calling, you can refer to the [OpenAI documentation](https://platform.openai.com/docs/assistants/tools/defining-functions).
98168

99169
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.
100170

101-
---
171+
#### What is this step for?
102172

103-
# 👨‍💻 Repository
173+
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.
174+
175+
176+
</details>
177+
<details>
178+
<summary><b>Step 5:</b> Running the application and testing</summary><br>
179+
180+
Run your application and this will allow you to test the assistant.
181+
182+
```bash
183+
# use this if you are using the repository:
184+
npm run start:dev
185+
186+
# if you are using your own NestJS application, please check the npm scripts in the package.json file
187+
# defualt command for NestJS is:
188+
npm run start
189+
```
190+
191+
Then you can test the assistant.
192+
1. First, you need to create a thread. You can create one
193+
by sending a POST request to the `/assistant/threads` endpoint with the **empty object in the body**.
194+
2. Then you can send a message to the assistant by sending a POST request to the `/assistant/chat` endpoint with the following body:
195+
```json
196+
{
197+
"threadId": "your-thread-id",
198+
"content": "Hello, how are you?"
199+
}
200+
```
201+
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.
202+
203+
Congrats! You have successfully integrated the AI Assistant library into your NestJS application. 🎉
204+
205+
</details>
206+
207+
## 🤔 Are you stuck?
104208

105209
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).
106210

107-
---
211+
Boldare's engineers are here to help you. If you have any questions or need help with the implementation, feel free to [book a call](https://calendly.com/olivier-halupczok/30min) with one of our engineers.
212+
213+
Learn more how **[Boldare can help you with AI development](https://www.boldare.com/services/ai-software-development-consulting/)**.
214+
215+
You can also ask questions in the [GitHub Discussions](https://github.com/boldare/openai-assistant/discussions) section.
216+
217+
218+
## Contributions
219+
220+
Would you like to see new features in the library?
221+
- You can freely contribute to the project! Just create a pull request with your changes.
222+
- [Talk your idea over with one of our engineers.](https://calendly.com/olivier-halupczok/30min)
223+
- You can also [post your idea here](https://github.com/boldare/openai-assistant/discussions).
108224

109-
# License
225+
## License
110226

111-
`@boldare/openai-assistant` is MIT licensed
227+
`@boldare/openai-assistant` and this repository is MIT licensed

0 commit comments

Comments
 (0)