# Lightspeed plugin for Backstage

Red Hat Developer Lightspeed for Red Hat Developer Hub (Developer Lightspeed for RHDH) is a virtual assistant powered by generative AI that offers in-depth insights into Red Hat Developer Hub (RHDH), including its wide range of capabilities. You can interact with this assistant to explore and learn more about RHDH in greater detail.

Developer Lightspeed for RHDH provides a natural language interface within the RHDH console, helping you easily find information about the product, understand its features, and get answers to your questions as they come up.

## For administrators

### Prerequisites

- Follow the lightspeed backend plugin [README](https://github.com/redhat-developer/rhdh-plugins/blob/main/workspaces/lightspeed/plugins/lightspeed-backend/README.md) to integrate lightspeed backend in your Backstage instance.

**Note**

### Permission Framework Support

The Lightspeed plugin has support for the permission framework.

- When [RBAC permission](https://github.com/backstage/community-plugins/tree/main/workspaces/rbac/plugins/rbac-backend#installation) framework is enabled, for non-admin users to access lightspeed UI, the role associated with your user should have the following permission policies associated with it. Add the following in your permission policies configuration file named `rbac-policy.csv`:

```CSV
p, role:default/team_a, lightspeed.chat.read, read, allow
p, role:default/team_a, lightspeed.chat.create, create, allow
p, role:default/team_a, lightspeed.chat.delete, delete, allow
p, role:default/team_a, lightspeed.chat.update, update, allow

# Required for Notebooks feature (if enabled)
p, role:default/team_a, lightspeed.notebooks.use, update, allow

g, user:default/<your-user-name>, role:default/team_a

```

You can specify the path to this configuration file in your application configuration:

```yaml
permission:
  enabled: true
  rbac:
    policies-csv-file: /some/path/rbac-policy.csv
    policyFileReload: true
```

### Installation

1. Install the Lightspeed plugin using the following command:

   ```console
   yarn workspace app add @red-hat-developer-hub/backstage-plugin-lightspeed
   ```

### Configuration

1. Add a new nav item **Lightspeed** in App `packages/app/src/App.tsx`:

   ```tsx title="packages/app/src/components/App.tsx"
   /* highlight-add-next-line */ import { LightspeedPage } from '@red-hat-developer-hub/backstage-plugin-lightspeed';

   <Route path="/lightspeed" element={<LightspeedPage />} />;
   ```

2. Enable **Lightspeed** page in `packages/app/src/components/Root/Root.tsx`:

   ```tsx title="packages/app/src/components/Root/Root.tsx"
   /* highlight-add-next-line */ import { LightspeedIcon } from '@red-hat-developer-hub/backstage-plugin-lightspeed';

   <SidebarItem
     icon={LightspeedIcon as IconComponent}
     to="lightspeed"
     text="Lightspeed"
   />;
   ```

## For users

### Using the Lightspeed plugin in Backstage

Lightspeed is a front-end plugin that enables you to interact with any LLM server running a model with OpenAI's API compatibility.

#### Prerequisites

- Your Backstage application is installed and running.
- You have installed the Lightspeed plugin. For installation process, see [Installation](#installation).

#### Procedure

1. Open your Backstage application and select a Lightspeed nav item from the **Navigation**.
2. Ask your questions to the Lightspeed chatbot.

### Display modes and chat continuity

Lightspeed supports multiple **display modes** from Settings (for example overlay, docked, embedded, and fullscreen). Switching modes can remount the chat surface; your **current conversation** and **tool-call metadata** for that thread stay with the session so the active chat is not reset. Live streaming text may not update continuously across a mode switch until the assistant response finishes loading.

### MCP servers settings

Lightspeed includes an MCP servers settings panel where users can:

- View configured MCP servers and current status
- Enable or disable eligible servers
- Configure a personal token per server
- See inline status and validation feedback

#### Token validation behavior

When configuring a server token in the settings modal, the token is validated
automatically after typing stops briefly. The input shows inline feedback:

- Success: `Connection successful`
- Error: `Authorization failed. Try again.`

Users can then save the configuration after validation feedback is displayed.

### Notebooks (Developer Preview)

Notebooks is an experimental feature that enables **document-based conversations with Retrieval-Augmented Generation (RAG)**. This feature allows you to:

- **Create persistent notebook sessions** with their own vector databases
- **Upload and manage documents** to query against, including:
  - Text files (`.txt`, `.md`, `.log`)
  - PDF documents with automatic text extraction
  - Structured data (`.json`, `.yaml`)
  - Web content via URL (up to 20MB per file)
- **Query your documents** using natural language and get context-aware AI responses
- **Organize documents** by sessions with metadata and tagging
- **Maintain context** across conversations - all uploaded documents remain available throughout the session

#### How Notebooks Works

1. **Session Management**: Create a notebook session, which is backed by its own vector database
2. **Document Upload**: Upload documents - they are automatically processed, chunked, and embedded into the vector database
3. **RAG Conversations**: Ask questions about your documents - relevant chunks are retrieved and provided as context to the LLM
4. **Persistent Storage**: Your documents and conversations remain available throughout the session lifecycle

#### Prerequisites for Notebooks

- Notebooks requires a **Lightspeed Stack service** to be running
- The backend administrator must enable the feature (see [Backend Configuration](../lightspeed-backend/README.md#notebooks-developer-preview))
- Users need the appropriate RBAC permissions (if enabled)

#### Using Notebooks

1. Ensure Notebooks is enabled in your Backstage instance
2. Navigate to the Lightspeed page
3. Create a new notebook session or select an existing one
4. Upload documents you want to query
5. Start asking questions about your uploaded documents

For backend configuration and API details, administrators should refer to the [Lightspeed Backend Plugin Documentation](../lightspeed-backend/README.md#notebooks-developer-preview).

## Loading as Dynamic Plugin

#### To configure Lightspeed plugin into Red Hat Developer Hub use this configuration:

- Load the lightspeed plugin from the npm registry

```
global:
  dynamic:
    includes:
      - dynamic-plugins.default.yaml
    plugins:
    - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-lightspeed:next__0.6.1!red-hat-developer-hub-backstage-plugin-lightspeed
      disabled: false
      pluginConfig:
        lightspeed:
          # OPTIONAL: Custom users prompts displayed to users
          # If not provided, the plugin uses built-in default prompts
          prompts:
            - title: 'Getting Started with Red Hat Developer Hub'
              message: Can you guide me through the first steps to start using Developer Hub
                as a developer, like exploring the Software Catalog and adding my
                service?
        dynamicPlugins:
          frontend:
            red-hat-developer-hub.backstage-plugin-lightspeed:
              translationResources:
                - importName: lightspeedTranslations
                  module: Alpha
                  ref: lightspeedTranslationRef
              dynamicRoutes:
                - path: /lightspeed
                  importName: LightspeedPage
              mountPoints:
                - mountPoint: application/listener
                  importName: LightspeedFAB
                - mountPoint: application/provider
                  importName: LightspeedDrawerProvider
                - mountPoint: application/internal/drawer-state
                  importName: LightspeedDrawerStateExposer
                - mountPoint: application/internal/drawer-content
                  importName: LightspeedChatContainer
                  config:
                    id: lightspeed
                    priority: 100
```

- add the lightspeed configuration in the `app-config.yaml`

```
  prompts: # optional
    - title: <prompt_title>
      message: <prompt_message>
```

---

#### To install this plugin locally in [RHDH](https://github.com/redhat-developer/rhdh) application as a dynamic plugin.

Follow the below steps -

- Export dynamic plugin assets. This will build and create the static assets for the plugin and put it inside dynamic-plugins-root folder.

`yarn install`

`yarn tsc`

`yarn build`

`npx @red-hat-developer-hub/cli plugin export --dynamic-plugins-root <path-to>/rhdh/dynamic-plugins-root`

- Add the extension point inside the `app-config.yaml` or `app-config.local.yaml` file.

```yaml
dynamicPlugins:
  frontend:
    red-hat-developer-hub.backstage-plugin-lightspeed:
      translationResources:
        - importName: lightspeedTranslations
          module: Alpha
          ref: lightspeedTranslationRef
      dynamicRoutes:
        - path: /lightspeed
          importName: LightspeedPage
      mountPoints:
        - mountPoint: application/listener
          importName: LightspeedFAB
        - mountPoint: application/provider
          importName: LightspeedDrawerProvider
        - mountPoint: application/internal/drawer-state
          importName: LightspeedDrawerStateExposer
        - mountPoint: application/internal/drawer-content
          importName: LightspeedChatContainer
          config:
            id: lightspeed
            priority: 100
```