@rainbird/sdk-react-material

A package that builds on @rainbird/sdk and @rainbird/sdk-react and adds some Material-UI. Best suited for those that want to get up and running as quickly as possible.

Installation

yarn add @rainbird/sdk-react-material

npm i @rainbird/sdk-react-material

Usage

Components | Styles

Components

Agent | QueryList | KitchenSink | Rainbird | Configuration | Modal | Interaction | Result | Select | ErrorBoundary

Agent

Agent is the quickest way to embed a Rainbird agent into your app. It handles:

• the initial query configuration step when subject and/or object is missing
• session start and initial query
• follow-up question handling
• results, evidence links, reset and optional custom session support

import React from "react";
import { createMuiTheme } from "@material-ui/core/styles";
import { Agent } from "@rainbird/sdk-react-material";

const theme = createMuiTheme({
  primary: { main: "#1c083b" },
  secondary: { main: "#4fbbc5" },
});

export const App = () => (
  <Agent
    apiKey="myApiKey"
    baseURL="https://test-api.rainbird.ai"
    kmID="myKmID"
    subject="David"
    relationship="speaks"
    object=""
    theme={theme} // optional
    options={{}} // optional
    appURL="https://test.rainbird.ai" // optional but needed to display evidence link
    displayEvidence={true} // optional, defaults to true
    evidenceKey="" // optional but needed for evidence links behind authentication
    allowUndoResults={false} // optional, defaults to false
    allowCustomSession={false} // optional, defaults to false
  />
);

Agent also supports customising the query configuration step. This is useful when you already know whether the user needs to supply a subject, an object, or both. This also works when one side of the query is already fixed and only the missing side should be requested from the user.

import React from "react";
import { Agent } from "@rainbird/sdk-react-material";

export const App = () => (
  <Agent
    apiKey="myApiKey"
    baseURL="https://test-api.rainbird.ai"
    kmID="myKmID"
    relationship="speaks"
    subject=""
    object=""
    configurationProps={{
      prompt: "Enter the person to run this query.",
      objectConfig: { hidden: true }, // intentionally not asking for object
      subjectConfig: {
        label: "Person",
        placeholder: "Enter Person...",
        testID: "person-pre-query",
      },
    }}
  />
);

If you want to control how result text is rendered, pass formatResult.

import React from "react";
import { Agent } from "@rainbird/sdk-react-material";

export const App = () => (
  <Agent
    apiKey="myApiKey"
    baseURL="https://test-api.rainbird.ai"
    kmID="myKmID"
    subject="David"
    relationship="speaks"
    object="English"
    formatResult={({ certainty, object, subject }) =>
      `${subject} speaks the ${object} language with ${certainty}% confidence`
    }
  />
);

Agent supports the following customisation points in addition to the standard Rainbird props:

• configurationProps: passed through to Configuration
• formatResult(result): customises the text rendered for each result row
• header: set to null to hide the default header, pass a node to replace it, or pass a render function if you want full control over the header content
• headerProps / headerStyle: customise the header wrapper
• contentProps / contentStyle: customise the main content container
• setSubject, setObject, setSessionID: optional callbacks for observing subject, object, and session state changes inside the agent
• sessionID: optional starting session ID if you want to resume an existing session
• theme: optional Material-UI theme, defaults to RBTheme

QueryList

QueryList loads an agent config, displays the available queries, and launches the selected query with the existing Agent runtime.

import React from "react";
import { QueryList } from "@rainbird/sdk-react-material";

export const App = () => (
  <QueryList
    appURL="https://test.rainbird.ai"
    baseURL="https://test-api.rainbird.ai"
    config={{
      agentName: "Language agent",
      goals: [
        {
          _id: "query-1",
          description: "Who speaks French?",
          rel: "speaks",
          subjectInstance: "David",
          objectInstance: "French",
        },
      ],
      kbId: "myKmID",
    }}
  />
);

QueryList accepts:

• config or configURL: agent configuration source
• agentID and appURL: used together when QueryList should fetch config itself
• title, subtitle: optional header overrides
• showQueryText: shows the configured query text under each query name
• contentProps, contentStyle: customise the main wrapper
• theme: optional Material-UI theme, defaults to RBTheme

For public-agent integrations where session start must happen outside the browser, pass loadSessionID.

<QueryList
  agentID="agent-id"
  appURL="https://app.rainbird.ai"
  baseURL="https://api.rainbird.ai"
  config={agentConfig}
  loadSessionID={async ({ agentConfig, agentID, query }) => {
    const response = await fetch(`/queryagent/${agentID}/start`, {
      credentials: "include",
    });
    const data = await response.json();
    return data.sessionId;
  }}
/>

loadSessionID receives { agentConfig, agentID, query } and must resolve a sessionID. If it rejects, QueryList shows the error and returns the user to the query list.

KitchenSink

KitchenSink is an opinionated wrapper around Agent that gives you a ready-made Rainbird experience with minimal setup. It is useful for quick integrations, Storybook demos and internal prototypes. For production integrations where you want more control over layout and presentation, Agent is the recommended starting point because it provides the same core runtime behavior without the extra wrapper styling.

import React from "react";
import { createMuiTheme } from "@material-ui/core/styles";
import { KitchenSink } from "@rainbird/sdk-react-material";

const theme = createMuiTheme({
  primary: {
    main: "#1c083b",
  },
  secondary: {
    main: "#4fbbc5",
  },
});

export const App = () => (
  <KitchenSink
    apiKey="myApiKey"
    baseURL="https://test-api.rainbird.ai"
    kmID="myKmID"
    subject="Bob"
    relationship="speaks"
    object=""
    theme={theme} // optional
    options={{}} // optional
    appURL="https://test.rainbird.ai" // optional but needed to display evidence link
    displayEvidence={true} // optional, defaults to true
    evidenceKey="" // optional but needed for evidence links behind authentication, use in conjunction with displayEvidence & appURL to configure displaying evidence for results
    allowUndoResults={false} // optional, defaults to false
    allowCustomSession={false} // optional, defaults to false
  />
);

Rainbird

Rainbird is the lower-level interaction runtime used by Agent. It starts or resumes a session, makes the initial query and renders either Interaction or Result. Recommended for people who want the supported Rainbird runtime but want to own their own wrapper, configuration step and layout.

import React from "react";
import { createMuiTheme } from "@material-ui/core/styles";
import { Rainbird } from "@rainbird/sdk-react-material";

const theme = createMuiTheme({
  primary: {
    main: "#1c083b",
  },
  secondary: {
    main: "#4fbbc5",
  },
});

export const App = () => (
  <MyCustomWrapper>
    <Rainbird
      apiKey="myApiKey"
      baseURL="https://test-api.rainbird.ai"
      kmID="myKmID"
      subject="Bob"
      relationship="speaks"
      object=""
      onError={(err, errInfo) => {
        logErrorToCustomService(err, errInfo);
        return <CustomErrorComponent />;
      }}
      theme={theme} // optional
      options={{}} // optional
      appURL="https://test.rainbird.ai" // optional but needed to display evidence link
      displayEvidence={true} // optional, defaults to true
      evidenceKey="" // optional but needed for evidence links behind authentication, use in conjunction with displayEvidence & appURL to configure displaying evidence for results
      allowUndoResults={false} // optional, defaults to false
      formatResult={({ certainty, object, subject }) =>
        `${subject} speaks the ${object} language with ${certainty}% confidence`
      } // optional
    />
  </MyCustomWrapper>
);

Configuration

Configuration is the pre-query form used by Agent. Use it directly if you want to build your own launch flow but keep the same Material UI controls.

import React from "react";
import { Configuration } from "@rainbird/sdk-react-material";

export const App = () => (
  <Configuration
    prompt="Enter the person to run this query."
    objectConfig={{ hidden: true }}
    subjectConfig={{
      label: "Person",
      placeholder: "Enter Person...",
      testID: "person-pre-query",
    }}
    setSubject={(value) => console.log(value)}
    setObject={(value) => console.log(value)}
    setSessionID={(value) => console.log(value)}
  />
);

Supported configuration props:

• prompt: replaces the default “Subject and/or Object not found...” copy
• subjectConfig, objectConfig, sessionIDConfig: each accepts:
  • hidden: hides that field
  • label: field label
  • placeholder: input placeholder
  • testID: override the rendered data-testid
  • testId: supported as a backward-compatible alias
• allowCustomSession: shows the optional session field unless sessionIDConfig.hidden is true
• onSubmit: optional callback fired after the configuration form is submitted

Modal

Modal is a thin wrapper around MUI Dialog for hosting Rainbird SDK components or your own UI inside a consistent modal shell. Use it to drop an agent or custom flow into your app with optional header and actions.

import React from "react";
import { Modal } from "@rainbird/sdk-react-material";

export const App = () => (
  <Modal open onClose={() => {}} title="SDK Modal">
    <div style={{ padding: 24 }}>Your agent or UI goes here.</div>
  </Modal>
);

Content-only, full-bleed layout (no header, no padding):

import React from "react";
import { Modal } from "@rainbird/sdk-react-material";

export const App = () => (
  <Modal open onClose={() => {}} showCloseButton={false} contentPadding={0}>
    <MyAgent style={{ height: "100%", width: "100%" }} />
  </Modal>
);

Custom header and full screen:

import React from "react";
import { Modal } from "@rainbird/sdk-react-material";

export const App = () => (
  <Modal
    open
    onClose={() => {}}
    header={<MyHeader />}
    dialogProps={{ fullScreen: true }}
    showCloseButton={false}
  >
    <MyAgent />
  </Modal>
);

If you need the close button to sit inside a custom header, pass a header render function instead of a static node. The render function receives closeButton, onClose, and titleID, so you can place the button inside your own header layout or omit it entirely.

import React from "react";
import { Box, Typography } from "@material-ui/core";
import { Modal } from "@rainbird/sdk-react-material";

export const App = () => (
  <Modal
    open
    onClose={() => {}}
    header={({ closeButton, titleID }) => (
      <Box
        alignItems="center"
        display="flex"
        justifyContent="space-between"
        style={{ background: "#1c083b", color: "white", padding: "16px 24px" }}
      >
        <div />
        <Typography component="h2" id={titleID} variant="h4">
          Try Query
        </Typography>
        <div>{closeButton}</div>
      </Box>
    )}
  >
    <div style={{ padding: 24 }}>Your agent or UI goes here.</div>
  </Modal>
);

Interaction

The Interaction component is simply the interaction with Rainbird; it won't start a session or make the initial query for you. This component is recommended for those that wish to have a custom results page/start process/query process. If you choose this component, it would be worth checking out the @rainbird/sdk-react to complement it. This can be styled by wrapping it in a ThemeProvider from MUI.

import React from 'react';
import { RESPONSE_TYPE_QUESTION } from '@rainbird/sdk';
import { Rainbird } from '@rainbird/sdk-react';
import { Interaction } from '@rainbird/sdk-react-material';

const theme = createMuiTheme({
    primary: {
        main: '#1c083b'
    },
    secondary: {
        main: '#4fbbc5'
    }
})

export const App = () => (
    <MyCustomWrapper>
        <Rainbird>
            {({data, type}) => {
                if (type === RESPONSE_TYPE_QUESTION) return <Interaction data={data}>
            }}
        </Rainbird>
    </MyCustomWrapper>
)

Result

The Result component simply displays the results from a RESPONSE_TYPE_RESULT. Similarly to the Interaction component, you may want to checkout the @rainbird/sdk-react. It can also be styled by wrapping it in a ThemeProvider from MUI.

import React from 'react';
import { RESPONSE_TYPE_QUESTION, RESPONSE_TYPE_RESULT } from '@rainbird/sdk';
import { Rainbird } from '@rainbird/sdk-react';
import { Interaction, Result } from '@rainbird/sdk-react-material';

const theme = createMuiTheme({
    primary: {
        main: '#1c083b'
    },
    secondary: {
        main: '#4fbbc5'
    }
})

export const App = () => (
    <MyCustomWrapper>
        <Rainbird>
            {({data, type}) => {
                if (type === RESPONSE_TYPE_QUESTION) return <Interaction data={data}>
                if (type === RESPONSE_TYPE_RESULT) return (
                  <Result
                    data={data}
                    formatResult={({ certainty, object, subject }) =>
                      `${subject} speaks the ${object} language with ${certainty}% confidence`
                    }
                  />
                )
            }}
        </Rainbird>
    </MyCustomWrapper>
)

formatResult(result) is optional. If omitted, the default text is: {subject} {relationship} {object} - {certainty}%

Select

The select components map to the props needed for the FormControl component in the @rainbird/sdk-react package. These are all included in the KitchenSink, Rainbird and Interaction components, however you can import them directly to use in custom builds. Any props supported in the MUI docs are supported. All can be themed by wrapping them in a MUI ThemeProvider

Certainty | MultiString | MultiStringAdd | SingleDate | SingleNumber | SingleString | SingleStringAdd | SingleTruth

Certainty A MUI slider from 1-100 to determine the certainty of a response.

MultiString A multi select component with search capability. Doesn't allow a user to add custom responses. Built using MUIs AutoComplete.

MultiStringAdd A multi select component with search capability. Allows a user to add custom responses.Built using MUIs AutoComplete.

SingleDate A date TextField

MultiDate A custom multi select date component. Built using MUIs DatePicker and AutoComplete.

SingleNumber A number TextField

SingleString A select component with search capability. Doesn't allow a user to add a custom response. Built using MUIs AutoComplete.

SingleStringAdd A select component with search capability. Allows a user to add a custom response.Built using MUIs AutoComplete.

SingleTruth Two radio buttons for 'True' and 'False'. Built using Radio, RadioGroup, FormControlLabel and FormControl. Props can be added to them by using radioProps, radioGroupProps, formControlLabelProps and formControlProps respectively.

ErrorBoundary

The error boundary is a very simple boundary that catches thrown errors bubbling up to the window. On an error, it stops rendering children and calls the onError prop. It's built into the KitchenSink and Rainbird components, so it's recommended for more custom solutions.

export const App = () => (
  <ErrorBoundary
    onError={(err, errInfo) => {
      logErrorToService(err);
      return <ErrorPage error={error} info={errInfo} />;
    }}
  >
    <CustomApp />
  </ErrorBoundary>
);

Styles

RBTheme

If you wanted to use our theme for your entire app, then the theme object is here. Created using createMuiTheme from MUI.