# @virtual-protocol/react-virtual-ai

> `@virtual-protocol/react-virtual-ai` is a React client SDK that offers a collection of React UI components to easily integrate with VIRTUAL. For non-React frontend frameworks, we also provide several JavaScript helper functions and services to help ease t

Latest version **0.0.140** (published 2024-06-10) · 0 weekly downloads

## Install

```sh
npm install @virtual-protocol/react-virtual-ai
pnpm add @virtual-protocol/react-virtual-ai
yarn add @virtual-protocol/react-virtual-ai
bun add @virtual-protocol/react-virtual-ai
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; large bundle; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.140 |
| Published | 2024-06-10 |
| First published | 2024-04-01 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 13 |
| Unpacked size | 10.8 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | jiaxiong8169 |

## Links

- npm: https://www.npmjs.com/package/@virtual-protocol/react-virtual-ai
- npm.io page: https://npm.io/package/@virtual-protocol/react-virtual-ai

## Dependencies (13)

- [gsap](https://npm.io/package/gsap.md) ^3.12.5
- [three](https://npm.io/package/three.md) ^0.160.0
- [jwt-decode](https://npm.io/package/jwt-decode.md) ^4.0.0
- [mmd-parser](https://npm.io/package/mmd-parser.md) ^1.0.4
- [react-icons](https://npm.io/package/react-icons.md) ^5.0.1
- [framer-motion](https://npm.io/package/framer-motion.md) ^11.0.5
- [@emotion/react](https://npm.io/package/@emotion/react.md) ^11.11.3
- [@emotion/styled](https://npm.io/package/@emotion/styled.md) ^11.11.0
- [@chakra-ui/react](https://npm.io/package/@chakra-ui/react.md) ^2.8.2
- [@pixiv/three-vrm](https://npm.io/package/@pixiv/three-vrm.md) ^2.1.0
- [@react-three/drei](https://npm.io/package/@react-three/drei.md) ^9.97.5
- [@react-three/fiber](https://npm.io/package/@react-three/fiber.md) ^8.15.16
- [react-audio-voice-recorder](https://npm.io/package/react-audio-voice-recorder.md) ^2.2.0

## Recent versions

- 0.0.140 (latest) — 2024-06-10
- 0.0.138 — 2024-05-23
- 0.0.137 — 2024-05-23
- 0.0.136 — 2024-05-23
- 0.0.135 — 2024-05-06
- 0.0.134 — 2024-05-02
- 0.0.133 — 2024-04-26
- 0.0.132 — 2024-04-26
- 0.0.131 — 2024-04-25
- 0.0.130 — 2024-04-25
- 0.0.129 — 2024-04-24
- 0.0.128 — 2024-04-22
- 0.0.127 — 2024-04-22
- 0.0.126 — 2024-04-22
- 0.0.125 — 2024-04-22
- … 21 more at https://npm.io/package/@virtual-protocol/react-virtual-ai/versions

## README

# Introduction

`@virtual-protocol/react-virtual-ai` is a React client SDK that offers a collection of React UI components to easily integrate with VIRTUAL. For non-React frontend frameworks, we also provide several JavaScript helper functions and services to help ease the integration.

Gitbook: https://virtualprotocol.gitbook.io/whitepaper/technical-documentation/modular-consensus-framework/inference-by-dapps

## Examples

Examples are available here: https://github.com/Virtual-Protocol/react-virtual-ai/tree/main/src/examples

## Features

1. **Plug-and-Play Integration with VIRTUAL**: Integrate conversational AI 3D models into your React applications by utilizing the customizable components.

2. **Customizable Services and Hooks**: To implement own components, you can use the `useVirtual` hook and other helper functions and classes to build your own components that integrate with VIRTUAL.

## Usage

To install `@virtual-protocol/react-virtual-ai` in your React project, follow these simple steps:

### Step 1: Installation

```bash
npm install @virtual-protocol/react-virtual-ai --save
```

or

```bash
yarn add @virtual-protocol/react-virtual-ai
```

Reference: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry

### Step 2: Obtain Your API Key and Secret

Follow the VIRTUAL documentation on creating API key and secret.

### Step 3: Implement `initAccessToken` function

`initAccessToken` prop is available for `CharacterRoom` component and `useVirtual` hook. The access token returned via this function will be used as the authorization of the runner service.

> **_IMPORTANT NOTE:_** The `UNSAFE_initAccessToken` function is provided as an example implementation, please do not use it in production as exposing API key and secret is unsafe. To enable `UNSAFE_initAccessToken`, pass in metadata props to the `CharacterRoom` or `useVirtual` hook.

Sample metadata payload when using `UNSAFE_initAccessToken` function:

```javascript
metadata={{
  apiKey: "<YOUR VIRTUAL API KEY>",
  apiSecret: "<YOUR VIRTUAL API SECRET>",
  userUid: "1", // any unique user identifier that will be used for runner memory core to remember conversations
  userName: "User", // user's name that the Virtual will address as
  }}
```

Recommended implementation of initAccessToken function:

```javascript
// This function fetches runner access token and keep in cache
export const initAccessToken = async (
  virtualId: number,
  metadata?: { [id: string]: any }
) => {
  if (!virtualId) return "";
  // runner token by bot is saved as runnerToken<virtualId> in localStorage
  let cachedRunnerToken = localStorage.getItem(`runnerToken${virtualId}`) ?? "";
  // Fetch a new runner token if expired
  if (!cachedRunnerToken || !validateJwt(cachedRunnerToken)) {
    // Get runner token via your own dapp server
    const accessToken = localStorage.getItem("accessToken");
    if (!accessToken) return "";
    const resp = await fetch(`${YOUR_BACKEND_URL}/api/auth/token`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        virtualId: virtualId,
        metadata: metadata,
      }),
    });
    const respJson = await resp.json();
    cachedRunnerToken = respJson.runnerToken ?? "";
    localStorage.setItem(`runnerToken${virtualId}`, cachedRunnerToken);
  }
  return cachedRunnerToken;
};
```

### Step 4: Insert the `CharacterRoom` component

There

```jsx
import {
  CharacterRoom,
  UNSAFE_initAccessToken,
} from "@virtual-protocol/react-virtual-ai";

return (
  <CharacterRoom
    userName="User"
    virtualName="Virtual Name"
    virtualId={1} // unique virtual id in number / string that will define the
    initAccessToken={UNSAFE_initAccessToken}
  />
);
```

## VirtualService

The VirtualService class contains all operations that communicate with the Virtual runner service. It is also used in the `useVirtual` hook to get the prompt responses.

```javascript
const virtualService = new VirtualService({
  virtualId: 1,
  userName: "",
  virtualName: "",
  initAccessToken: undefined,
  onPromptError: undefined,
  metadata: undefined,
});
```

## Other Usages

There are also other services and functions that you can explore to customize your own components

### useVirtual hook

This hook is a wrapper to the `VirtualService` class that allows you to communicate with Virtual with the functions returned such as `createPrompt` and `virtualService.getTTSResponse`.

```javascript
const { modelUrl, createPrompt, virtualService } = useVirtual({
  virtualId: 1,
  userName: "",
  virtualName: "",
  initAccessToken: undefined,
  onPromptError: undefined,
  metadata: undefined,
});
```

### Utils

There are several util functions provided, you may utilize separately for specific cases.

`UNSAFE_initAccessToken`: Default function to generate access token. DO NOT use this in production.

`validateJwt`: Validate JWT token expiry

`getVirtualRunnerUrl`: Get virtual runner URL via JWT token

`getQuotedTexts`: Get quoted texts as list via string input

`loadAnimation`: Load VMD / Mixamo FBX animation into VRM model

`fadeByEmotion`: Fade in facial expression for the VRM model

`blink`: Blink the VRM model's eyes

### Components

`AICharacter`: 3D Character with PresentationControl. Must wrap inside ThreeJS Canvas. Utilized in CharacterScene.

`CharacterScene`: 3D Character with Scene. May use this for displaying 3D model and animations. Utilized in CharacterRoom.

`CharacterInput`: Input component for prompting. Utilized in CharacterRoom.

`CharacterRoom`: Full component for React Virtual AI.

### Services

`VirtualService`: VirtualService contains all operations required to send prompt to the VIRTUAL.

`VrmService`: VrmService provides functions to load VRM model and fade to animations.

## API References

JSDocs comments are available in the components, classes and functions. Kindly follow the comments for more details.

## Contributing

We welcome contributions! If you find a bug or have a feature request, please open an issue. Pull requests are also appreciated.

---
_Source: https://npm.io/package/@virtual-protocol/react-virtual-ai · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
