From 865560e768c71e534e2f42d2af80bfc3e51d7aa9 Mon Sep 17 00:00:00 2001 From: "pawel.piwowarczyk@allegro.com" Date: Thu, 16 Jan 2025 15:58:09 +0100 Subject: [PATCH] docs: add docs how to install and use backstage chat-bot --- CONTRIBUTING.md | 2 +- .../chat-bot/chat-bot-backend/CHANGELOG.md | 10 ++ plugins/chat-bot/chat-bot-backend/README.md | 166 ++++++++++++++++-- .../chat-bot-backend/chat-bot-backend.rest | 64 +++++++ plugins/chat-bot/chat-bot-common/CHANGELOG.md | 10 ++ plugins/chat-bot/chat-bot-common/README.md | 2 +- plugins/chat-bot/chat-bot/CHANGELOG.md | 10 ++ plugins/chat-bot/chat-bot/README.md | 48 +++-- 8 files changed, 266 insertions(+), 46 deletions(-) create mode 100644 plugins/chat-bot/chat-bot-backend/CHANGELOG.md create mode 100644 plugins/chat-bot/chat-bot-backend/chat-bot-backend.rest create mode 100644 plugins/chat-bot/chat-bot-common/CHANGELOG.md create mode 100644 plugins/chat-bot/chat-bot/CHANGELOG.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff65a3e..adf3935 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ - if issue exists, reference it from PR title or description using GitHub magic words like _resolves #issue-number_ - before making significant changes, please contact us via issues to discuss your plans and decrease number of changes after Pull Request is created - create pull requests to **main** branch -- recommended to use conventional commits standard +- required to use conventional commits standard - when updating a package, make sure to: - update its README.md - update its CHANGELOG.md diff --git a/plugins/chat-bot/chat-bot-backend/CHANGELOG.md b/plugins/chat-bot/chat-bot-backend/CHANGELOG.md new file mode 100644 index 0000000..591058e --- /dev/null +++ b/plugins/chat-bot/chat-bot-backend/CHANGELOG.md @@ -0,0 +1,10 @@ +# @allegro/backstage-plugin-chat-bot-common + +All notable changes to this plugin will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres +to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.1.0] - 2025-01-16 + +- Initial version of Backstage Chat Bot backend plugin diff --git a/plugins/chat-bot/chat-bot-backend/README.md b/plugins/chat-bot/chat-bot-backend/README.md index 32e8540..666762d 100644 --- a/plugins/chat-bot/chat-bot-backend/README.md +++ b/plugins/chat-bot/chat-bot-backend/README.md @@ -1,34 +1,166 @@ -# chat-bot +# ChatBot Backend -Welcome to the chat-bot backend plugin! +This ChatBot Backend plugin is primarily responsible for the following: -_This plugin was created through the Backstage CLI_ +- Process prompts from users based on the search module consume index to find the best matching answers. We are consuming [Azure Open AI](https://azure.microsoft.com/en-us/products/ai-services/openai-service) so you need to have an instance of service available and configured +- Provides endpoint for ChatBot dialog frontend plugin +- Provides endpoint for Slack integration +- Provides endpoint for Copilot integration -## Getting started +## Install -Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn -start` in the root directory, and then navigating to [/chat-bot/health](http://localhost:7007/api/chat-bot/health). +### Up and running -You can also serve the plugin in isolation by running `yarn start` in the plugin directory. -This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. -It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. +Steps to execute: + +1. First we need to add the `@allegro/backstage-plugin-chat-bot-backend` package to your backend: + +```sh + # From your Backstage root directory + yarn --cwd packages/backend add @allegro/backstage-plugin-chat-bot-backend +``` + +2. The ADR backend plugin has support for the [new backend system](https://backstage.io/docs/backend-system/), here's how you can set that up: + +In your `packages/backend/src/index.ts` make the following changes: -TODO: +```diff + const backend = createBackend(); -- install package -- preReq - auth.environement in app-config.yaml or local file ++ backend.add(import('@allegro/backstage-plugin-chat-bot-backend')); + +// ... other feature additions + + backend.start(); +``` + +### Setup Config + +First, you need to be sure that you set up [search feature](https://backstage.io/docs/features/search/) and that your Tech Docs and other documentation you want to use are indexed properly. + +Additionally, the plugin is used optionally for the development/debug reasons section: + +```yaml +auth: + environment: development +``` -Modify you configuration file, for example: +To set the plugin properly you need to provide at least. ```yaml # In app-config.yaml chatBot: - key: AzureOpenAIAccessKey # Access key to yout instance of Azure OpenAI Services + key: AzureOpenAIAccessKey # Access key to your instance of Azure OpenAI Services endpoint: AzureOpenAIEndpoint # Endpoint of your instance of Azure OpenAI Services ``` -TODO: +Additionally, you can play with models of your choice. + +```yaml +# In app-config.yaml +chatBot: + chatCompletionPrimaryModel: gpt-4o # default + chatCompletionSecondaryModel: gpt-4o-mini # default + embeddingModel: text-embedding-ada-002-d1 # default +``` + +#### Slack integration + +1. You need to set a list of slack channels that are allowed to use endpoints + +```yaml +# In app-config.yaml +chatBot: + slackChannels: [Backstage__ChatBot__Slack__Channel] +``` + +2. You need to configure `externalAccess` to endpoints, for example, static tokens like: + +```yaml +# In app-config.yaml +backend: + # Used for enabling authentication, the secret is shared by all backend plugins + # See https://backstage.io/docs/auth/service-to-service-auth for + # Information on the format + auth: + externalAccess: + - type: static + options: + token: ${Backstage--SlackBot--Token} + subject: index-search-for-help-slack-bot + # Restrictions are optional; see below + accessRestrictions: + - plugin: chat-bot +``` + +3. TODO: Slack configuration + +#### Copilot integration + +1. You need to set a list of organizations that are allowed to use endpoints + +```yaml +# In app-config.yaml +chatBot: + copilot: + github: + allowedOrganizations: + ['${Backstage__ChatBot__Copilot__Allowed__Organization}'] +``` + +2. You need to configure `externalAccess` to endpoints, for example, static tokens like: + +```yaml +# In app-config.yaml +backend: + # Used for enabling authentication, the secret is shared by all backend plugins + # See https://backstage.io/docs/auth/service-to-service-auth for + # Information on the format + auth: + externalAccess: + - type: static + options: + token: ${Backstage--Copilot--Token} + subject: index-search-for-copilot + # Restrictions are optional; see below + accessRestrictions: + - plugin: chat-bot +``` + +3. TODO: setup copilot + +## How assistant works + +### 1. User Interaction -- describe other configs -- model defaults +The user begins by asking a question within the Backstage interface. + +### 2. Multi-Query Retrieval + +The assistant modifies the user's original question into multiple query variations using a multi-query retriever mechanism. This helps to capture different ways the question could be interpreted. + +### 3. Search Execution + +Each generated query is passed to the Backstage search engine, which retrieves the top 3 relevant results for each query. + +### 4. Document Filtering + +The results are processed using an [embeddings](https://platform.openai.com/docs/guides/embeddings) model. By applying [cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity), the assistant identifies which documents most likely contain the answer to the user's question. + +### 5. Context Building + +The selected documents are passed to the AI model as context to provide relevant information for the answer generation. + +### 6. Answer Generation + +Using the provided context, the AI assistant generates a precise and informative response for the user. + +## Working with source code + +Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn +start` in the root directory, and then navigate to [/chat-bot/health](http://localhost:7007/api/chat-bot/health). + +You can also serve the plugin in isolation by running `yarn start` in the plugin directory. +This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. +It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory. diff --git a/plugins/chat-bot/chat-bot-backend/chat-bot-backend.rest b/plugins/chat-bot/chat-bot-backend/chat-bot-backend.rest new file mode 100644 index 0000000..09805c6 --- /dev/null +++ b/plugins/chat-bot/chat-bot-backend/chat-bot-backend.rest @@ -0,0 +1,64 @@ +### Bot prompt +POST http://localhost:7007/api/chat-bot/prompt +Content-Type: application/json + +{ + "content": "Why we use Backstage as techincal platform?" +} + +### Bot slack web hook event +POST http://localhost:7007/api/chat-bot/slack/event +Content-Type: application/json + +{ + "token": "token", + "team_id": "T00000000", + "api_app_id": "A000000000", + "event": { + "user": "U00000000", + "type": "app_mention", + "ts": "1730186477.797779", + "client_msg_id": "e1cfc69e-7d15-4e5b-98dc-bb808e5e1f49", + "text": "<@U00000000> I ran the k8s optimizer across all of our Allegro microservices, and each one is under-allocated. When should we add pods, and when should we scale vertically? Is there a specific strategy? The optimizer only considers CPU and memory—so what’s the heuristic for deciding when to add pods? If it suggests 2x, do we just add another pod?", + "team": "T00000000", + "thread_ts": "1730128480.851819", + "parent_user_id": "U00000000", + "blocks": [ + { + "type": "rich_text", + "block_id": "FTzco", + "elements": [ + { + "type": "rich_text_section", + "elements": [ + { + "type": "user", + "user_id": "U00000000" + }, + { + "type": "text", + "text": " I ran the k8s optimizer across all of our Allegro microservices, and each one is under-allocated. When should we add pods, and when should we scale vertically? Is there a specific strategy? The optimizer only considers CPU and memory—so what’s the heuristic for deciding when to add pods? If it suggests 2x, do we just add another pod?" + } + ] + } + ] + } + ], + "channel": "C000000000", + "event_ts": "1730186477.797779" + }, + "type": "event_callback", + "event_id": "Ev07UL0WPABS", + "event_time": 1730186477, + "authorizations": [ + { + "enterprise_id": null, + "team_id": "T00000000", + "user_id": "U000000000", + "is_bot": true, + "is_enterprise_install": false + } + ], + "is_ext_shared_channel": false, + "event_context": "4-eyJldCI6ImFwcF9tZW50aW9uIiwidGlkIjoiVDAyNkU1MTJSIiwiYWlkIjoiQTA3UkpGRUo4SkoiLCJjaWQiOiJDMDdTOVVaOVNCQyJ9" +} \ No newline at end of file diff --git a/plugins/chat-bot/chat-bot-common/CHANGELOG.md b/plugins/chat-bot/chat-bot-common/CHANGELOG.md new file mode 100644 index 0000000..916b619 --- /dev/null +++ b/plugins/chat-bot/chat-bot-common/CHANGELOG.md @@ -0,0 +1,10 @@ +# @allegro/backstage-plugin-chat-bot-common + +All notable changes to this plugin will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres +to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.1.0] - 2025-01-16 + +- Initial version of Backstage Chat Bot plugin common diff --git a/plugins/chat-bot/chat-bot-common/README.md b/plugins/chat-bot/chat-bot-common/README.md index 707f54d..83df9ed 100644 --- a/plugins/chat-bot/chat-bot-common/README.md +++ b/plugins/chat-bot/chat-bot-common/README.md @@ -1,4 +1,4 @@ -# @internal/backstage-plugin-chat-bot-common +# ChatBot Common Welcome to the common package for the chat-bot plugin! diff --git a/plugins/chat-bot/chat-bot/CHANGELOG.md b/plugins/chat-bot/chat-bot/CHANGELOG.md new file mode 100644 index 0000000..14fef60 --- /dev/null +++ b/plugins/chat-bot/chat-bot/CHANGELOG.md @@ -0,0 +1,10 @@ +# @allegro/backstage-plugin-chat-bot + +All notable changes to this plugin will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres +to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.1.0] - 2025-01-16 + +- Initial version of Backstage Chat Bot plugin diff --git a/plugins/chat-bot/chat-bot/README.md b/plugins/chat-bot/chat-bot/README.md index 262053f..41aab45 100644 --- a/plugins/chat-bot/chat-bot/README.md +++ b/plugins/chat-bot/chat-bot/README.md @@ -4,11 +4,22 @@ This Spotify Backstage plugin integrates an AI-powered assistant using [Azure OpenAI Service](https://azure.microsoft.com/en-us/products/ai-services/openai-service) and the [Backstage search engine](https://github.com/backstage/backstage/tree/master/plugins/search) to provide smart, contextual responses to your questions. The assistant can automate routine tasks, offer intelligent suggestions, and help you quickly find relevant information within your Backstage environment. Designed to enhance productivity, it seamlessly integrates into your workflow, making it easier to manage and interact with Spotify services. -## Configuration +## Install -TODO: add package +### Up and running -Modify your app routes to include the ChatButton component, for example: +Steps to execute: + +1. First we need to add the `@allegro/backstage-plugin-chat-bot` package to your backend: + +```sh + # From your Backstage root directory + yarn --cwd packages/app add @allegro/backstage-plugin-chat-bot +``` + +2. Make sure the [@allegro/backstage-plugin-chat-bot-backend](../chat-bot-backend/README.md) is installed. + +3. Modify your app routes to include the ChatButton component, for example: ```tsx // In packages/app/src/App.tsx @@ -21,7 +32,7 @@ export default app.createRoot( {routes} } > @@ -31,28 +42,11 @@ export default app.createRoot( ); ``` -## How assistant works - -#### 1. User Interaction: - -The user begins by asking a question within the Backstage interface. - -#### 2. Multi-Query Retrieval: - -The assistant modifies the user's original question into multiple query variations using a multi-query retriever mechanism. This helps to capture different ways the question could be interpreted. - -#### 3. Search Execution: - -Each generated query is passed to the Backstage search engine, which retrieves the top 3 relevant results for each query. - -#### 4. Document Filtering: - -The results are processed using an [embeddings](https://platform.openai.com/docs/guides/embeddings) model. By applying [cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity), the assistant identifies which documents most likely contain the answer to the user's question. - -#### 5. Context Building: - -The selected documents are passed to the AI model as context to provide relevant information for the answer generation. +## Working with source code -#### 6. Answer Generation: +Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn +start` in the root directory, and then navigate to [home](http://localhost:3000). -Using the provided context, the AI assistant generates a precise and informative response for the user. +You can also serve the plugin in isolation by running `yarn start` in the plugin directory. +This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads. +It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.