kotaemon/docs/pages/app/functional-description.md

User group / tenant management

Create new user group

(6 man-days)

Description: each client has a dedicated user group. Each user group has an admin user who can do administrative tasks (e.g. creating user account in that user group...). The workflow for creating new user group is as follow:

1. Cinnamon accesses the user group management UI.
2. On "Create user group" panel, we supply: a. Client name: e.g. Apple. b. Sub-domain name: e.g. apple. c. Admin email, username & password.
3. The system will: a. An Aurora Platform deployment with the specified sub-domain. b. Send an email to the admin, with the username & password.

Expectation:

• The admin can go to the deployed Aurora Platform.
• The admin can login with the specified username & password.

Condition:

• When sub-domain name already exists, raise error.
• If error sending email to the client, raise the error, and delete the newly-created user-group.
• Password rule:
  • Have at least 8 characters.
  • Must contain uppercase, lowercase, number and symbols.

---

Delete user group

(2 man-days)

Description: in the tenant management page, we can delete the selected user group. The user flow is as follow:

1. Cinnamon accesses the user group management UI,
2. View list of user groups.
3. Next to target user group, click delete.
4. Confirm whether to delete.
5. If Yes, delete the user group. If No, cancel the operation.

Expectation: when a user group is deleted, we expect to delete everything related to the user groups: domain, files, databases, caches, deployments.

User management

---

Create user account (for admin user)

(1 man-day)

Description: the admin user in the client's account can create user account for that user group. To create the new user, the client admin do:

1. Navigate to "Admin" > "Users"
2. In the "Create user" panel, supply:
   • Username
   • Password
   • Confirm password
3. Click "Create"

Expectation:

• The user can create the account.
• The username:
  • Is case-insensitive (e.g. Moon and moon will be the same)
  • Can only contains these characters: a-z A-Z 0-9 _ + - .
  • Has maximum length of 32 characters
• The password is subjected to the following rule:
  • 8-character minimum length
  • Contains at least 1 number
  • Contains at least 1 lowercase letter
  • Contains at least 1 uppercase letter
  • Contains at least 1 special character from the following set, or a non-leading, non-trailing space character: ^ $ * . [ ] { } ( ) ? - " ! @ # % & / \ , > < ' : ; | _ ~ + =

---

Delete user account (for admin user)

Description: the admin user in the client's account can delete user account. Once an user account is deleted, he/she cannot login to Aurora Platform.

1. The admin user navigates to "Admin" > "Users".
2. In the user list panel, next to the username, the admin click on the "Delete" button. The Confirmation dialog appears.
3. If "Delete", the user account is deleted. If "Cancel", do nothing. The Confirmation dialog disappears.

Expectation:

• Once the user is deleted, the following information relating to the user will be deleted:
  • His/her personal setting.
  • His/her conversations.
• The following information relating to the user will still be retained:
  • His/her uploaded files.

---

Edit user account (for admin user)

Description: the admin user can change any information about the user account, including password. To change user information:

1. The admin user navigates to "Admin" > "Users".
2. In the user list panel, next to the username, the admin click on the "Edit" button.
3. The user list disappears, the user detail appears, with the following information show up:
   • Username: (prefilled the username)
   • Password: (blank)
   • Confirm password: (blank)
4. The admin can edit any of the information, and click "Save" or "Cancel".
   • If "Save": the information will be updated to the database, or show error per Expectation below.
   • If "Cancel": skip.
5. If Save success or Cancel, transfer back to the user list UI, where the user information is updated accordingly.

Expectation:

• If the "Password" & "Confirm password" are different from each other, show error: "Password mismatch".
• If both "Password" & *"Confirm password" are blank, don't change the user password.
• If changing password, the password rule is subjected to the same rule when creating user.
• It's possible to change username. If changing username, the target user has to use the new username.

---

Sign-in

(3 man-days)

Description: the users can sign-in to Aurora Platform as follow:

1. User navigates to the URL.
2. If the user is not logged in, the UI just shows the login screen.
3. User types username & password.
4. If correct, the user will proceed to normal working UI.
5. If incorrect, the login screen shows text error.

---

Sign-out

(1 man-day)

Description: the user can sign-out of Aurora Platform as follow:

1. User navigates to the Settings > User page.
2. User click on logout.
3. The user is signed out to the UI login screen.

Expectation: the user is completely signed out. Next time he/she uses the Aurora Platform, he/she has to login again.

---

Change password

Description: the user can change their password as follow:

1. User navigates to the Settings > User page.
2. In the change password section, the user provides these info and click Change:
   • Current password
   • New password
   • Confirm new password
3. If changing successfully, then the password is changed. Otherwise, show the error on the UI.

Expectation:

• If changing password succeeds, next time they logout/login to the system, they can use the new password.
• Password rule (Same as normal password rule when creating user)
• Errors:
  • Password does not match.
  • Violated password rules.

---

Chat

Chat to the bot

Description: the Aurora Platform focuses on question and answering over the uploaded data. Each chat has the following components:

• Chat message: show the exchange between bots and humans.
• Text input + send button: for the user to input the message.
• Data source panel: for selecting the files that will scope the context for the bot.
• Information panel: showing evidence as the bot answers user's questions.

The chat workflow looks as follow:

1. [Optional] User select files that they want to scope the context for the bot. If the user doesn't select any files, then all files on Aurora Platform will be the context for the bot.
   • The user can type multi-line messages, using "Shift + Enter" for line-break.
2. User sends the message (either clicking the Send button or hitting the Enter key).
3. The bot in the chat conversation will return "Thinking..." while it processes.
4. The information panel on the right begin to show data related to the user message.
5. The bot begins to generate answer. The "Thinking..." placeholder disappears..

Expecatation:

• Messages:
  • User can send multi-line messages, using "Shift + Enter" for line-break.
  • User can thumbs up, thumbs down the AI response. This information is recorded in the database.
  • User can click on a copy button on the chat message to copy the content to clipboard.
• Information panel:
  • The information panel shows the latest evidence.
  • The user can click on the message, and the reference for that message will show up on the "Reference panel" (feature in-planning).
  • The user can click on the title to show/hide the content.
  • The whole information panel can be collapsed.
• Chatbot quality:
  • The user can converse with the bot. The bot answer the user's requests in a natural manner.
  • The bot message should be streamed to the UI. The bot don't wait to gather alll the text response, then dump all of them at once.

Conversation - switch

Description: users can jump around between different conversations. They can see the list of all conversations, can select an old converation, and continue the chat under the context of the old conversation. The switching workflow is like this:

1. Users click on the conversation dropdown. It will show a list of conversations.
2. Within that dropdown, the user selects one conversation.
3. The chat messages, information panel, and selected data will show the content in that old chat.
4. The user can continue chatting as normal under the context of this old chat.

Expectation:

• In the conversation drop down list, the conversations are ordered in created date order.
• When there is no conversation, the conversation list is empty.
• When there is no conversation, the user can still converse with the chat bot. When doing so, it automatically create new conversation.

Conversation - create

Description: the user can explicitly start a new conversation with the chatbot:

1. User click on the "New" button.
2. The new conversation is automatically created.

Expectation:

• The default conversation name is the current datetime.
• It become selected.
• It is added to the conversation list.

Conversation - rename

Description: user can rename the chatbot by typing the name, and click on the Rename button next to it.

• If rename succeeds: the name shown in the 1st dropdown will change accordingly
• If rename doesn't succeed: show error message in red color below the rename section

Condition:

• Name constraint:
  • Min characters: 1
  • Max characters: 40
  • Could not having the same name with an existing conversation of the same user.

Conversation - delete

Description: user can delete the existing conversation as follow:

1. Click on Delete button.
2. The UI show confirmation with 2 buttons:
   • Delete
   • Cancel.
3. If Delete, delete the conversation, switch to the next oldest conversation, close the confirmation panel.
4. If cancel, just close the confirmation panel.

File management

The file management allows users to upload, list and delete files that they upload to the Aurora Platform

Upload file

Description: the user can upload files to the Aurora Platform. The uploaded files will be served as context for our chatbot to refer to when it converses with the user. To upload file, the user:

1. Navigate to the File tab.
2. Within the File tab, there is an Upload section.
3. User can add files to the Upload section through drag & drop, and or by click on the file browser.
4. User can select some options relating to uploading and indexing. Depending on the project, these options can be different. Nevertheless, they will discuss below.
5. User click on "Upload and Index" button.
6. The app show notifications when indexing starts and finishes, and when errors happen on the top right corner.

Options:

• Force re-index file. When user tries to upload files that already exists on the system:
  • If this option is True: will re-index those files.
  • If this option is False: will skip indexing those files.

Condition:

• Max number of files: 100 files.
• Max number of pages per file: 500 pages
• Max file size: 10 MB

List all files

Description: the user can know which files are on the system by:

1. Navigate to the File tab.
2. By default, it will show all the uploaded files, each with the following information: file name, file size, number of pages, uploaded date
3. The UI also shows total number of pages, and total number of sizes in MB.

Delete file

Description: users can delete files from this UI to free up the space, or to remove outdated information. To remove the files:

1. User navigate to the File tab.
2. In the list of file, next to each file, there is a Delete button.
3. The user clicks on the Delete button. Confirmation dialog appear.
4. If Delete, delete the file. If Cancel, close the confirmation dialog.

Expectation: once the file is deleted:

• The database entry of that file is deleted.
• The file is removed from "Chat - Data source".
• The total number of pages and MB sizes are reduced accordingly.
• The reference to the file in the information panel is still retained.