Release 1.0.6

This especially improves the introduction for when the bot has no
configured agents.

CHANGELOG.md

@@ -1,3 +1,11 @@
+# (2024-09-19) Version 1.0.6
+
+Improvements to:
+
+- messages sent by the bot - better onboarding flow, especially when no agents have been created yet
+- documentation pages
+
+
 # (2024-09-14) Version 1.0.5
 
 Further [improves](https://github.com/etkecc/baibot/commit/3b25b92a81a05ebaf1c6dbabf675fbfbe6c9f418) the typing notification logic, so that it tolerates edge cases better.

Cargo.lock

@@ -297,7 +297,7 @@ dependencies = [
 
 [[package]]
 name = "baibot"
-version = "1.0.5"
+version = "1.0.6"
 dependencies = [
  "anthropic-rs",
  "anyhow",

Cargo.toml

@@ -7,7 +7,7 @@ license = "AGPL-3.0-or-later"
 readme = "README.md"
 keywords = ["matrix", "chat", "bot", "AI", "LLM"]
 include = ["/etc/assets/baibot-torso-768.png", "/src", "/README.md", "/CHANGELOG.md", "/LICENSE"]
-version = "1.0.5"
+version = "1.0.6"
 edition = "2021"
 
 [lib]

docs/providers.md

@@ -23,17 +23,20 @@ The list of supported providers is below.
 
 ### How to choose a provider
 
-If you're not sure which provider to start with, we **recommend [OpenAI](#openai)** as it's the most popular and has the **widest range of capabilities**: [💬 text-generation](./features.md#-text-generation), [🖌️ image-generation](./features.md#️-image-generation), [🦻 speech-to-text](./features.md#-speech-to-text), [🗣️ text-to-speech](./features.md#️-text-to-speech).
+If you're not sure which provider to start with, **we recommend [OpenAI](#openai)** as it's the most popular and has the **widest range of capabilities**: [💬 text-generation](./features.md#-text-generation), [🖌️ image-generation](./features.md#️-image-generation), [🦻 speech-to-text](./features.md#-speech-to-text), [🗣️ text-to-speech](./features.md#️-text-to-speech).
 
 You don't need to choose just one though. The bot supports [mixing & matching models](./features.md#-mixing--matching-models), so you can use multiple providers at the same time.
 
 
 ### How to use a provider
 
-- sign up for it
-- obtain an API key
-- [create a new agent](./agents.md#creating-agents)
-- set it as a handler for some types of messages (see [Mixing & matching models](./features.md#-mixing--matching-models)) for a specific room or globally
+1. 📝 **Sign up for it**
+
+2. 🔑 **Obtain an API key**
+
+3. 🤖 **Create one or more agents** in a given room or globally. Next to each provider in the [list below](#supported-providers) you'll see **🗲 Quick start** commands, but you may also refer to the [agent creation guide](./agents.md#creating-agents).
+
+4. 🤝 **Set the new agent as a handler** for a given use-purpose like text-generation, image-generation, etc. The agent creation wizard will tell you how, but you may also refer to the [🤝 Handlers](./configuration/handlers.md) guide.
 
 
 ### Supported providers

src/agent/provider/localai/mod.rs

@@ -1,6 +1,5 @@
-// LocalAI is based on OpenAI (async-openai), because it seems to be fully compatible.
-// Moreover, openai_api_rust does not support speech-to-text, so if we wish to use this feature
-// we need to stick to async-openai.
+// At the time of testing, LocalAI can be powered by `openai`, but we use `openai_compat` for better reliability
+// in the event of future updates to `async-openai`.
 
 use super::openai_compat::Config;
 

src/controller/access/dispatching.rs

@@ -13,7 +13,7 @@ pub async fn dispatch_controller(
     match handler {
         AccessControllerType::Help => {}
         _ => {
-            if !message_context.sender_can_manage_global_config()? {
+            if !message_context.sender_can_manage_global_config() {
                 bot.messaging()
                     .send_error_markdown_no_fail(
                         message_context.room(),

src/controller/access/help.rs

@@ -80,24 +80,21 @@ fn build_section_users(
         message.push_str(&strings::access::users_no_patterns());
     }
 
-    let can_manage_global_config = message_context.sender_can_manage_global_config();
-    if let Ok(can_manage_global_config) = can_manage_global_config {
-        if can_manage_global_config {
-            message.push_str("\n\n");
+    if message_context.sender_can_manage_global_config() {
+        message.push_str("\n\n");
 
-            message.push_str(strings::the_following_commands_are_available());
-            message.push('\n');
+        message.push_str(strings::the_following_commands_are_available());
+        message.push('\n');
 
-            message.push_str(&strings::help::access::users_command_get(command_prefix));
-            message.push('\n');
+        message.push_str(&strings::help::access::users_command_get(command_prefix));
+        message.push('\n');
 
-            message.push_str(&strings::help::access::users_command_set(command_prefix));
-            message.push_str("\n\n");
+        message.push_str(&strings::help::access::users_command_set(command_prefix));
+        message.push_str("\n\n");
 
-            message.push_str(&strings::help::access::example_user_patterns(
-                homeserver_name,
-            ));
-        }
+        message.push_str(&strings::help::access::example_user_patterns(
+            homeserver_name,
+        ));
     }
 
     message
@@ -156,27 +153,24 @@ fn build_section_room_local_agent_managers(
         message.push_str(&strings::access::room_local_agent_managers_no_patterns());
     }
 
-    let can_manage_global_config = message_context.sender_can_manage_global_config();
-    if let Ok(can_manage_global_config) = can_manage_global_config {
-        if can_manage_global_config {
-            message.push_str("\n\n");
-            message.push_str(strings::the_following_commands_are_available());
-            message.push('\n');
+    if message_context.sender_can_manage_global_config() {
+        message.push_str("\n\n");
+        message.push_str(strings::the_following_commands_are_available());
+        message.push('\n');
 
-            message.push_str(
-                &strings::help::access::room_local_agent_managers_command_get(command_prefix),
-            );
-            message.push('\n');
+        message.push_str(
+            &strings::help::access::room_local_agent_managers_command_get(command_prefix),
+        );
+        message.push('\n');
 
-            message.push_str(
-                &strings::help::access::room_local_agent_managers_command_set(command_prefix),
-            );
-            message.push_str("\n\n");
+        message.push_str(
+            &strings::help::access::room_local_agent_managers_command_set(command_prefix),
+        );
+        message.push_str("\n\n");
 
-            message.push_str(&strings::help::access::example_user_patterns(
-                homeserver_name,
-            ));
-        }
+        message.push_str(&strings::help::access::example_user_patterns(
+            homeserver_name,
+        ));
     }
 
     message

src/controller/agent/create/mod.rs

@@ -138,7 +138,7 @@ pub async fn handle_global(
     provider: &str,
     agent_id_prefixless: &str,
 ) -> anyhow::Result<()> {
-    if !message_context.sender_can_manage_global_config()? {
+    if !message_context.sender_can_manage_global_config() {
         bot.messaging()
             .send_error_markdown_no_fail(
                 message_context.room(),

src/controller/agent/delete/mod.rs

@@ -50,7 +50,7 @@ pub async fn handle(
                 .await
         }
         PublicIdentifier::DynamicGlobal(_) => {
-            if !message_context.sender_can_manage_global_config()? {
+            if !message_context.sender_can_manage_global_config() {
                 bot.messaging()
                     .send_error_markdown_no_fail(
                         message_context.room(),

src/controller/agent/details/mod.rs

@@ -47,7 +47,7 @@ pub async fn handle(
             }
         }
         PublicIdentifier::DynamicGlobal(_) => {
-            if !message_context.sender_can_manage_global_config()? {
+            if !message_context.sender_can_manage_global_config() {
                 bot.messaging()
                     .send_error_markdown_no_fail(
                         message_context.room(),

src/controller/agent/help/mod.rs

@@ -12,10 +12,7 @@ pub async fn handle(bot: &Bot, message_context: &MessageContext) -> anyhow::Resu
 
     message.push_str(&format!("## {}", strings::help::agent::heading()));
     message.push_str("\n\n");
-    message.push_str(&strings::help::agent::intro(
-        bot.command_prefix(),
-        can_manage_agents,
-    ));
+    message.push_str(&strings::help::agent::intro(bot.command_prefix()));
     message.push('\n');
     message.push_str(&strings::help::agent::intro_capabilities());
     message.push_str("\n\n");
@@ -39,7 +36,7 @@ pub async fn handle(bot: &Bot, message_context: &MessageContext) -> anyhow::Resu
         ));
         message.push('\n');
 
-        if message_context.sender_can_manage_global_config()? {
+        if message_context.sender_can_manage_global_config() {
             message.push_str(&strings::help::agent::create_agent_global(
                 bot.command_prefix(),
             ));

src/controller/cfg/dispatching/mod.rs

@@ -40,7 +40,7 @@ async fn dispatch_config_related_handler(
     bot: &Bot,
 ) -> anyhow::Result<()> {
     if let SettingsStorageSource::Global = config_type {
-        if !message_context.sender_can_manage_global_config()? {
+        if !message_context.sender_can_manage_global_config() {
             bot.messaging()
                 .send_error_markdown_no_fail(
                     message_context.room(),

src/controller/help/mod.rs

@@ -3,7 +3,7 @@ use mxlink::MessageResponseType;
 use crate::{entity::MessageContext, strings, Bot};
 
 pub async fn handle(bot: &Bot, message_context: &MessageContext) -> anyhow::Result<()> {
-    let sender_can_manage_global_config = message_context.sender_can_manage_global_config()?;
+    let sender_can_manage_global_config = message_context.sender_can_manage_global_config();
     let sender_can_manage_room_local_agents =
         message_context.sender_can_manage_room_local_agents()?;
 
@@ -18,10 +18,7 @@ pub async fn handle(bot: &Bot, message_context: &MessageContext) -> anyhow::Resu
     // Agents
     message.push_str(&format!("## {}", strings::help::agent::heading()));
     message.push_str("\n\n");
-    message.push_str(&strings::help::agent::intro(
-        bot.command_prefix(),
-        sender_can_manage_room_local_agents,
-    ));
+    message.push_str(&strings::help::agent::intro(bot.command_prefix()));
     message.push_str("\n\n");
     message.push_str(&strings::help::agent::intro_handler_relation(
         bot.command_prefix(),

src/controller/provider/mod.rs

@@ -9,17 +9,8 @@ pub fn determine_controller(_text: &str) -> ControllerType {
 }
 
 pub async fn handle_help(message_context: &MessageContext, bot: &Bot) -> anyhow::Result<()> {
-    if !message_context.sender_can_manage_room_local_agents()? {
-        bot.messaging()
-            .send_error_markdown_no_fail(
-                message_context.room(),
-                &strings::provider::not_allowed(),
-                MessageResponseType::Reply(message_context.thread_info().root_event_id.clone()),
-            )
-            .await;
-
-        return Ok(());
-    }
+    let can_create_global_agents = message_context.sender_can_manage_global_config();
+    let can_create_room_local_agents = message_context.sender_can_manage_room_local_agents()?;
 
     let mut message = String::new();
     message.push_str(&format!("## {}", strings::help::provider::heading()));
@@ -69,18 +60,28 @@ pub async fn handle_help(message_context: &MessageContext, bot: &Bot) -> anyhow:
             &provider_info,
         ));
 
-        message.push_str("- 🗲 Quick start:\n");
-        message.push_str(&format!(
-            "\t- create a room-local agent: `{command_prefix} agent create-room-local {provider_id} my-{provider_id}-agent`",
-            command_prefix = bot.command_prefix(),
-            provider_id = provider.to_static_str(),
-        ));
-        message.push('\n');
-        message.push_str(&format!(
-            "\t- create a global agent: `{command_prefix} agent create-global {provider_id} my-{provider_id}-agent`",
-            command_prefix = bot.command_prefix(),
-            provider_id = provider.to_static_str(),
-        ));
+        // We always show a "Quick start" section (even to unprivileged users),
+        // because we're talking about it in a previous message.
+        message.push_str("- 🗲 Quick start:");
+        if can_create_room_local_agents {
+            message.push_str(&format!(
+                "\n\t- create a room-local agent: `{command_prefix} agent create-room-local {provider_id} my-{provider_id}-agent`",
+                command_prefix = bot.command_prefix(),
+                provider_id = provider.to_static_str(),
+            ));
+        }
+        if can_create_global_agents {
+            message.push_str(&format!(
+                "\n\t- create a global agent: `{command_prefix} agent create-global {provider_id} my-{provider_id}-agent`",
+                command_prefix = bot.command_prefix(),
+                provider_id = provider.to_static_str(),
+            ));
+        }
+        if !can_create_room_local_agents && !can_create_global_agents {
+            message.push_str(&format!(
+                " ask an administrator to create an agent for you (you lack permissions to do so yourself)",
+            ));
+        }
 
         message.push_str("\n\n");
     }

src/entity/message_context.rs

@@ -70,12 +70,12 @@ impl MessageContext {
         &self.thread_info
     }
 
-    pub fn sender_can_manage_global_config(&self) -> anyhow::Result<bool> {
-        Ok(self.trigger_event_info.sender_is_admin)
+    pub fn sender_can_manage_global_config(&self) -> bool {
+        self.trigger_event_info.sender_is_admin
     }
 
-    pub fn sender_can_manage_room_local_agents(&self) -> anyhow::Result<bool> {
-        Ok(self.sender_can_manage_global_config()?
+    pub fn sender_can_manage_room_local_agents(&self) -> mxidwc::Result<bool> {
+        Ok(self.sender_can_manage_global_config()
             || self.sender_is_allowed_room_local_agent_manager()?)
     }
 
@@ -102,21 +102,8 @@ impl MessageContext {
         combined
     }
 
-    fn sender_is_allowed_room_local_agent_manager(&self) -> anyhow::Result<bool> {
-        match &self
-            .global_config()
-            .access
-            .room_local_agent_manager_patterns
-        {
-            None => Ok(false),
-            Some(patterns) => {
-                let allowed_regexes = mxidwc::parse_patterns_vector(patterns)?;
-
-                Ok(mxidwc::match_user_id(
-                    self.sender_id().as_str(),
-                    &allowed_regexes,
-                ))
-            }
-        }
+    fn sender_is_allowed_room_local_agent_manager(&self) -> mxidwc::Result<bool> {
+        self.room_config_context()
+            .is_user_allowed_room_local_agent_manager(self.sender_id().clone())
     }
 }

src/entity/room_config_context.rs

@@ -1,3 +1,5 @@
+use mxlink::matrix_sdk::ruma::OwnedUserId;
+
 use super::globalconfig::GlobalConfig;
 use super::roomconfig::RoomConfig;
 
@@ -180,4 +182,18 @@ impl RoomConfigContext {
                     .clone()
             })
     }
+
+    pub fn is_user_allowed_room_local_agent_manager(
+        &self,
+        user_id: OwnedUserId,
+    ) -> mxidwc::Result<bool> {
+        match &self.global_config.access.room_local_agent_manager_patterns {
+            None => Ok(false),
+            Some(patterns) => {
+                let allowed_regexes = mxidwc::parse_patterns_vector(patterns)?;
+
+                Ok(mxidwc::match_user_id(user_id.as_str(), &allowed_regexes))
+            }
+        }
+    }
 }

src/strings/agent.rs

@@ -44,7 +44,7 @@ pub fn not_allowed_to_manage_static_agents() -> String {
 
 pub fn configuration_does_not_result_in_a_working_agent(err: anyhow::Error) -> String {
     format!(
-        "The provided configuration does not result in a working agent. The following error was encountered when trying to talk to the agent API:\n```\n{}```",
+        "The provided configuration does not result in a working agent. The following error was encountered when trying to talk to the agent API:\n```\n{}\n```",
         err,
     )
 }

src/strings/help/agent.rs

@@ -2,15 +2,8 @@ pub fn heading() -> String {
     "🤖 Agents".to_owned()
 }
 
-pub fn intro(command_prefix: &str, can_see_providers: bool) -> String {
-    format!(
-        "An agent is an instantiation and configuration of some **☁️ provider**{}.",
-        if can_see_providers {
-            format!(" (see `{command_prefix} provider`)")
-        } else {
-            "".to_owned()
-        }
-    )
+pub fn intro(command_prefix: &str) -> String {
+    format!("An agent is an instantiation and configuration of some **☁️ provider** (see `{command_prefix} provider`).")
 }
 
 pub fn intro_handler_relation(command_prefix: &str) -> String {
@@ -24,7 +17,7 @@ pub fn intro_capabilities() -> String {
 }
 
 pub fn no_permission_to_create_agents() -> &'static str {
-    "You are neither an administrator, nor a room-local agent manager, so **you cannot create new agents by yourself**."
+    "⚠️ You are neither a bot administrator, nor a room-local agent manager, so **you cannot create new agents by yourself**."
 }
 
 pub fn list_agents(command_prefix: &str) -> String {

src/strings/introduction.rs

@@ -23,20 +23,6 @@ fn purposes_intro() -> &'static str {
     "I can typically be used for the following purposes:"
 }
 
-fn no_text_generation_handler_agent() -> String {
-    format!(
-        "There is no configured handler agent which supports {} {}.",
-        AgentPurpose::TextGeneration.emoji(),
-        AgentPurpose::TextGeneration
-    )
-}
-
-fn introduction_outro(command_prefix: &str) -> String {
-    format!(
-        "You may also send a `{command_prefix} help` command message in this room for more information."
-    )
-}
-
 pub async fn create_on_join_introduction(
     name: &str,
     command_prefix: &str,
@@ -111,18 +97,17 @@ pub async fn create_on_join_introduction(
     message.push_str("\n\n");
 
     if got_text_generation_agent {
-        message.push_str(&simply_send_a_message(
+        message.push_str(&make_use_of_me_simply_send_a_message(
             command_prefix,
             room_config_context.text_generation_prefix_requirement_type(),
         ));
     } else {
-        message.push_str(&no_text_generation_handler_agent());
+        message.push_str(&make_use_of_me_agent_creation(
+            command_prefix,
+            room_config_context.text_generation_prefix_requirement_type(),
+        ));
     }
 
-    message.push_str("\n\n");
-
-    message.push_str(&introduction_outro(command_prefix));
-
     message
 }
 
@@ -130,17 +115,85 @@ pub fn create_short_introduction(name: &str) -> String {
     its_me(name)
 }
 
-fn simply_send_a_message(
+fn make_use_of_me_simply_send_a_message(
+    command_prefix: &str,
+    prefix_requirement_type: TextGenerationPrefixRequirementType,
+) -> String {
+    let message = r#"**To make use of me**:
+
+1. 👋 %send_a_message%
+2. 📖 %learn_more%
+"#;
+
+    message
+        .replace("%command_prefix%", command_prefix)
+        .replace(
+            "%send_a_message%",
+            &send_a_text_message(command_prefix, prefix_requirement_type),
+        )
+        .replace(
+            "%learn_more%",
+            &learn_more_from_usage_or_help(command_prefix),
+        )
+}
+
+fn make_use_of_me_agent_creation(
+    command_prefix: &str,
+    prefix_requirement_type: TextGenerationPrefixRequirementType,
+) -> String {
+    let message = r#"**To make use of me**:
+
+1. ☁️ **Choose an agent provider** (e.g. OpenAI, Mistral, etc). Send a `%command_prefix% provider` command to see the list.
+2. 🤖 %create_one_or_more_agents%
+3. 🤝 %set_new_agent_as_handler%
+4. 👋 %send_a_message%
+5. 📖 %learn_more%
+"#;
+
+    message
+        .replace("%command_prefix%", command_prefix)
+        .replace(
+            "%send_a_message%",
+            &send_a_text_message(command_prefix, prefix_requirement_type),
+        )
+        .replace(
+            "%learn_more%",
+            &learn_more_from_usage_or_help(command_prefix),
+        )
+        .replace(
+            "%create_one_or_more_agents%",
+            &create_one_or_more_agents(command_prefix),
+        )
+        .replace(
+            "%set_new_agent_as_handler%",
+            &set_new_agent_as_handler(command_prefix),
+        )
+}
+
+fn send_a_text_message(
     command_prefix: &str,
     prefix_requirement_type: TextGenerationPrefixRequirementType,
 ) -> String {
     match prefix_requirement_type {
         TextGenerationPrefixRequirementType::No => {
-            "**To make use of me, send a message** in this room (e.g. `Hello!`) and see me reply."
-                .to_owned()
+            "**Send a text message** in this room (e.g. `Hello!`) and see me reply.".to_owned()
         }
         TextGenerationPrefixRequirementType::CommandPrefix => {
-            format!("In this room, I'm configured to require the command prefix (`{command_prefix}`) for text messages.\n**To make use of me, send a prefixed text message** (e.g. `{command_prefix} Hello!`) and see me reply.")
+            format!("In this room, I'm configured to require the command prefix (`{command_prefix}`) for text messages. **Send a prefixed text message** (e.g. `{command_prefix} Hello!`) and see me reply.")
         }
     }
 }
+
+fn learn_more_from_usage_or_help(command_prefix: &str) -> String {
+    format!(
+        "**Learn more** by sending a `{command_prefix} usage` or `{command_prefix} help` command."
+    )
+}
+
+pub fn create_one_or_more_agents(command_prefix: &str) -> String {
+    format!("**Create one or more agents** in this room or globally. The provider help message will show you **🗲 Quick start** commands, but you may also send a `{command_prefix} agent` command to see the guide.")
+}
+
+pub fn set_new_agent_as_handler(command_prefix: &str) -> String {
+    format!("**Set the new agent as a handler** for a given use-purpose like text-generation, image-generation, etc. The agent-creation wizard will tell you how, but you may also send a `{command_prefix} config` command to see the guide (in the 🤖 *Handler Agents* section).")
+}

src/strings/provider.rs

@@ -25,10 +25,6 @@ pub fn invalid_configuration_for_provider(
     )
 }
 
-pub fn not_allowed() -> String {
-    "You are not allowed to see the providers list.".to_owned()
-}
-
 pub fn providers_list_intro() -> String {
     "The list of supported providers is below.".to_owned()
 }
@@ -39,7 +35,7 @@ pub fn help_how_to_choose_heading() -> String {
 
 pub fn help_how_to_choose_description(command_prefix: &str) -> String {
     let str = r#"
-If you're not sure which provider to start with, we **recommend OpenAI** as it's the most popular and has the **widest range of capabilities**.
+If you're not sure which provider to start with, **we recommend OpenAI** as it's the most popular and has the **widest range of capabilities**.
 
 You don't need to choose just one though. The bot supports **mixing & matching models** (by setting different handlers for different types of messages - see `%command_prefix% config`), so you can use multiple providers at the same time.
 "#;
@@ -55,13 +51,21 @@ pub fn help_how_to_use_heading() -> String {
 
 pub fn help_how_to_use_description(command_prefix: &str) -> String {
     let str = r#"
-- sign up for it
-- obtain an API key
-- create a new agent (see `%command_prefix% agent`)
-- set the new agent as a handler for some types of messages (see `%command_prefix% config`)
+1. 📝 **Sign up for it**
+2. 🔑 **Obtain an API key**
+3. 🤖 %create_one_or_more_agents%
+4. 🤝 %set_new_agent_as_handler%
 "#;
 
     str.replace("%command_prefix%", command_prefix)
+        .replace(
+            "%create_one_or_more_agents%",
+            &super::introduction::create_one_or_more_agents(command_prefix),
+        )
+        .replace(
+            "%set_new_agent_as_handler%",
+            &super::introduction::set_new_agent_as_handler(command_prefix),
+        )
         .trim()
         .to_owned()
 }

src/strings/usage.rs

@@ -12,7 +12,7 @@ If there's a text-generation handler agent configured (see `%command_prefix% con
 
 Whether the bot responds depends on the **💬 Text Generation / 🗟 Prefix Requirement** setting (see `%command_prefix% config status`).
 Sometimes, a prefix (e.g. `%command_prefix%`) is required in front of messages sent to the room for the bot to respond.
-For multi-user rooms, this setting defaults to "required"
+For multi-user rooms, this setting defaults to "required".
 
 Room messages start a threaded conversation where you can continue back-and-forth communication with the bot.