beakjs

Introduction to Beak.js

Beak.js is a powerful tool designed for developers who want to integrate customizable AI-powered assistants into their React applications. This open-source solution focuses on simplicity, functionality, and flexibility, making it accessible for developers at any skill level.

Key Features

• Built-in UI: Beak.js provides users with a beautifully designed chat window, which can be fully customized to match the style of your application.
• Ease of Use: Integrating Beak.js requires only a few lines of code, making it easy to add to any existing React application.
• Open Source: Distributed under the MIT license, Beak.js is free for anyone to use and contribute to, ensuring constant improvements and community support.

Getting Started

Installation

To get started with Beak.js, you need to add it to your React project via npm or yarn:

npm install @beakjs/react --save

# or with yarn
yarn add @beakjs/react

Setup

After installation, it's time to set up Beak.js. Wrap your app with the Beak component and include the assistant window within it:

import { Beak } from "@beakjs/react";

const App = () => (
  <Beak
    __unsafeOpenAIApiKey__="sk-..."
    instructions="Assistant is running in a web app and helps the user with XYZ."
  >
    <MyApp />
    <AssistantWindow />
  </Beak>
);

This addition places a functional chat window in the bottom right corner of your webpage, enabling interaction with the AI assistant.

Note: Avoid exposing your API key in public-facing applications. For secure deployment strategies that protect your API key, refer to the deployment section.

Integrating Beak.js with Your Application

To allow the assistant to perform tasks specific to your application, you can set up functions using useBeakFunction:

import { useBeakFunction } from "@beakjs/react";

const MyApp = () => {
  const [message, setMessage] = useState("Hello World!");

  useBeakFunction({
    name: "updateMessage",
    description: "This function updates the app's display message.",
    parameters: {
      message: {
        description: "A short message to display on screen.",
      },
    },
    handler: ({ message }) => {
      setMessage(message);

      return `Updated the message to: "${message}"`;
    },
  });

  return <div>{message}</div>;
};

These functions become accessible to the assistant as soon as their respective components are mounted, allowing it to perform context-specific tasks seamlessly.

Context Awareness

Keep the assistant informed of on-screen events using useBeakInfo:

import { useBeakInfo } from "@beakjs/react";

const MyApp = () => {
  const [message, setMessage] = useState("Hello World!");

  useBeakInfo("current message", message);

  // ...
};

By combining useBeakFunction and useBeakInfo, you empower the assistant to interact effectively with dynamic elements of your application.

Deployment

To securely manage API keys, Beak.js uses server-side handlers that safely forward requests to OpenAI. These handlers can also incorporate authentication and rate limiting. Supported frameworks include:

• Next.js
• Remix
• Express

Comprehensive documentation on secure deployment is available through the provided links.

Running the Demo

To explore the capabilities of Beak.js, you can run a demo by building the project and starting the demo application:

git clone [email protected]:mme/beakjs.git && cd beakjs
yarn && yarn build
cd demo/frontend/presentation
echo "VITE_OPENAI_API_KEY=sk-your-openai-key" > .env
yarn && yarn dev

Visit http://localhost:5173/ to see the demo in action.

Contribution and License

Beak.js welcomes contributions and suggestions. It’s distributed under the MIT license, allowing for broad usage and community collaboration.

Markus Ecker, 2023