-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add docs how to install and use backstage chat-bot
- Loading branch information
1 parent
5ab585a
commit 865560e
Showing
8 changed files
with
266 additions
and
46 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters