diff --git a/CHANGELOG.md b/CHANGELOG.md index 2df176e..c36dac8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # (2024-10-01) Version 1.2.0 -- (**Feature**) Adds support for [on-demand involvement](./docs/usage.md#on-demand-involvement) of the bot (via mention) in arbitrary threads and reply chains ([9908512968](https://github.com/etkecc/baibot/commit/990851296828168c2106eb3f4668833e9e5a7463)) - fixes [issue #15](https://github.com/etkecc/baibot/issues/15) +- (**Feature**) Adds support for [on-demand involvement](./docs/features.md#on-demand-involvement) of the bot (via mention) in arbitrary threads and reply chains ([9908512968](https://github.com/etkecc/baibot/commit/990851296828168c2106eb3f4668833e9e5a7463)) - fixes [issue #15](https://github.com/etkecc/baibot/issues/15) - (**Feature**) Simplifies [Transcribe-only mode](./docs/features.md#transcribe-only-mode) reply format (removing `> đŸĻģ` prefixing) to allow easier forwarding, etc. ([e6aa956423](https://github.com/etkecc/baibot/commit/e6aa95642376ee7d87932d0e66dcfedf261b188b)) - fixes [issue #14](https://github.com/etkecc/baibot/issues/14) diff --git a/docs/access.md b/docs/access.md index 68c11aa..54d8538 100644 --- a/docs/access.md +++ b/docs/access.md @@ -16,7 +16,7 @@ Users: - ✅ can **invite the bot to rooms** - ✅ can **use all the bot's [features](./features.md)** ([đŸ’Ŧ Text Generation](./features.md#-text-generation), [đŸĻģ Speech-to-Text](./features.md#-speech-to-text), etc.) by sending room messages -- ✅ can **mention the bot** in threads and reply chains to provoke it to respond to non-user messages (see [📖 Usage / đŸ’Ŧ Text Generation / On-demand involvement](./usage.md#on-demand-involvement)) +- ✅ can **mention the bot** in threads and reply chains to provoke it to respond to non-user messages (see [🌟 Features / đŸ’Ŧ Text Generation / On-demand involvement](./features.md#on-demand-involvement)) - ✅ can **change the bot's configuration in a room** (e.g. `!bai config room ...` commands) - ❌ cannot **change the bot's global configuration** (e.g. `!bai config global ...` commands) - ❌ cannot **create new [🤖 Agents](./agents.md)** (neither in rooms, nor globally). See [đŸ’ŧ Room-local agent managers](#-room-local-agent-managers) for controlling which users can create agents. diff --git a/docs/features.md b/docs/features.md index aff8288..bc84062 100644 --- a/docs/features.md +++ b/docs/features.md @@ -28,7 +28,7 @@ Text Generation is the bot's ability to **respond to users' text messages with t In multi-user (group) rooms, to avoid disturbing the normal conversation between people, the bot is auto-configured to only respond to messages starting with the command prefix (`!bai`) or direct mentions via the [đŸ’Ŧ Text Generation / 🗟 Prefix Requirement Type](./configuration/text-generation.md#-prefix-requirement-type) setting. -Normally, the bot only responds to allowed [đŸ‘Ĩ Users](./access.md#-users). In certain cases, it's useful for an allowed user to provoke the bot to respond even in foreign threads or reply chains. You can learn more about this feature in the [📖 Usage / đŸ’Ŧ Text Generation / On-demand involvement](./usage.md#on-demand-involvement) section. +Normally, the bot only responds to allowed [đŸ‘Ĩ Users](./access.md#-users). In certain cases, it's useful for an allowed user to provoke the bot to respond even in foreign threads or reply chains. You can learn more about this feature in the [On-demand involvement](./features.md#on-demand-involvement) section below. A few other features (like [đŸ—Ŗī¸ Text-to-Speech](#ī¸-text-to-speech) and [đŸĻģ Speech-to-Text](#-speech-to-text)) combine well with Text Generation, so you **don't necessarily need to communicate with the bot via text** (with [Seamless voice interaction](#seamless-voice-interaction), you can communicate only with voice). @@ -38,6 +38,22 @@ You may also wish to see: - [📖 Usage / đŸ’Ŧ Text Generation](./usage.md#-text-generation) section for more details on how to use the bot for Text Generation in a room +#### On-demand involvement + +In the following 2 cases, it's useful to involve the bot in conversations on-demand: + +1. In multi-user rooms (with the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting set to "required") +2. In rooms with foreign users (users that are not authorized bot [đŸ‘Ĩ users](./access.md#-users)) + +In these instances, an allowed [đŸ‘Ĩ user](./access.md#-users) can also provoke the bot to respond to **any** thread or reply chain by [mentioning](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) the bot (e.g. `@baibot Hello!`). The following screenshots demonstrate this behavior: + +- [đŸ–ŧī¸ On-demand involvement in the room](./screenshots/text-generation-prefix-requirement.webp) +- [đŸ–ŧī¸ On-demand involvement in a thread](./screenshots/text-generation-on-demand-thread-involvement.webp) (the Alice user in this example is not an allowed user, yet her messages are still considered as part of the conversation context) +- [đŸ–ŧī¸ On-demand involvement in a reply chain](./screenshots/text-generation-on-demand-reply-involvement.webp) (the Alice user in this example is not an allowed user, yet her messages are still considered as part of the conversation context) + +💡 **NOTE**: Normally, the bot **only considers messages from allowed [đŸ‘Ĩ Users](./access.md#-users)** and ignores all other messages when responding. However, **when the bot is explicitly invoked (via mention)** in a thread or reply chain, **it will consider all messages** in the thread and reply chain (even those from foreign users) as part of the conversation context. + + ### đŸ—Ŗī¸ Text-to-Speech Text-to-Speech is the bot's ability to **turn text messages into voice messages**. diff --git a/docs/usage.md b/docs/usage.md index 484365f..d49c80d 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -15,7 +15,7 @@ See screenshots of: - đŸ–ŧī¸ [the default Text Generation flow](./screenshots/text-generation.webp) in 1:1 rooms - đŸ–ŧī¸ [the Text Generation flow in multi-user rooms](./screenshots/text-generation-prefix-requirement.webp) (where the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting is auto-configured to "required") -- [on-demand involvement](#on-demand-involvement) +- the [on-demand involvement](./features.md#on-demand-involvement) feature Whether the bot responds depends on: @@ -25,27 +25,12 @@ Whether the bot responds depends on: - (🎨 agent capabilities) whether the configured `text-generation` (or `catch-all`) handler agent actually supports text-generation. The provider may lack support for this feature or it may be disabled in the [🤖 agents](./agents.md) configuration -- (the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting) whether a prefix (e.g. `!bai`) or user mention (e.g. `@baibot`) is required for messages sent to the room. For multi-user rooms, this setting defaults to "required". See [on-demand involvement](#on-demand-involvement) for details. +- (the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting) whether a prefix (e.g. `!bai`) or user mention (e.g. `@baibot`) is required for messages sent to the room. For multi-user rooms, this setting defaults to "required". See [🌟 Features / đŸ’Ŧ Text Generation / On-demand involvement](./features.md#on-demand-involvement) for details. -Room messages start a threaded conversation where you can continue back-and-forth communication with the bot. +Room messages start a threaded conversation where you can continue back-and-forth communication with the bot. Using [on-demand involvement](./features.md#on-demand-involvement), you can can also mention the bot to provoke it to get involved in any conversation thread or reply chain. Unless you've enabled the [â™ģī¸ Context Management](./features.md#ī¸-context-management) feature, all messages will be sent to the agent's API each time. If the context management feature is enabled, older messages may be dropped. -#### On-demand involvement - -In the following 2 cases, it's useful to involve the bot in conversations on-demand: - -1. For multi-user rooms (with the [🗟 Prefix Requirement](./configuration/text-generation.md#-prefix-requirement-type) setting set to "required") -2. In rooms with foreign users (users that are not authorized bot [đŸ‘Ĩ users](./access.md#-users)) - -In these instances, an allowed [đŸ‘Ĩ user](./access.md#-users) can also provoke the bot to respond to **any** thread or reply chain by [mentioning](https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions) the bot (e.g. `@baibot Hello!`). The following screenshots demonstrate this behavior: - -- [đŸ–ŧī¸ On-demand involvement in the room](./screenshots/text-generation-prefix-requirement.webp) -- [đŸ–ŧī¸ On-demand involvement in a thread](./screenshots/text-generation-on-demand-thread-involvement.webp) (the Alice user in this example is not an allowed user, yet her messages are still considered as part of the conversation context) -- [đŸ–ŧī¸ On-demand involvement in a reply chain](./screenshots/text-generation-on-demand-reply-involvement.webp) (the Alice user in this example is not an allowed user, yet her messages are still considered as part of the conversation context) - -💡 **NOTE**: Normally, the bot **only considers messages from allowed [đŸ‘Ĩ Users](./access.md#-users)** and ignores all other messages when responding. However, **when the bot is explicitly invoked (via mention)** in a thread or reply chain, **it will consider all messages** in the thread and reply chain (even those from foreign users) as part of the conversation context. - ### đŸ—Ŗī¸ Text-to-Speech