npm package: @mit-app-inventor/chatbot
Description: A pure JavaScript implementation of the MIT App Inventor ChatBot component.
Author: Evan W. Patton
Latest version: 2.0.0

# MIT App Inventor ChatBot.js

This package implements the ChatBot component from MIT App Inventor in
pure JavaScript.

## Install

```
npm install --save @mit-app-inventor/chatbot
```

## Usage

**NB:** To use the ChatBot, you will need a token from App Inventor
and an API key for the LLM service in question. You can either provide
the ApiKey directly in your source (not advised) or you can create a
short API key via https://chatbotadmin.appinventor.mit.edu/. The use
of a short key will prevent leaking your real API key in your sources
and the short key can only be used via the ChatBot proxy. You can
revoke short keys via the admin interface.

```javascript
import { ChatBot } from '@mit-app-inventor/chatbot';
const chatbot = new ChatBot('YOUR-TOKEN-HERE');
const response = await chatbot.Converse('What is 2+2?');
document.body.appendChild(document.createTextElement(response));
```

Additionally, you need a Token. For now, the easiest way to do this is
to navigate to https://code.appinventor.mit.edu and continue without
an account. In this new anonymous account, you can start a blank
project and then add a ChatBot to Screen1. From there, expand the
Advanced category under Properties and copy the Token value.

### API

The API of ChatBot generally follows the App Inventor blocks described
[here](https://ai2.appinventor.mit.edu/reference/components/experimental.html#ChatBot).
However, some minor enhancements have been made for the convenience of
developers writing JavaScript.

```javascript
// Idomatic App Inventor by providing the event handler
chatbot.GotResponse = (response) => {
  document.body.appendChild(document.createTextElement(response));
}
chatbot.Converse('What is 2+2?');  // This calls GotResponse eventually

// JavaScript await
const response = await chatbot.Converse('What is 2+2?');
document.body.appendChild(document.createTextElement(response));
```

#### Converse(question)

Asks the `question` of the ChatBot. This will call `GotResponse` with
the response text and return a `Promise` that will resolve when the
response is returned.

#### ConverseWithImage(question, source)

Asks the `question` of the ChatBot using the given `source` as an
image context. The `source` can be be an HTMLImageElement, an
HTMLCanvasElement, or a Blob that contains image data.

A `Promise` resolving to the response text will be returned, and the
`GotResponse` callback will also be run.

#### CreateImage(description)

Asks the ChatBot to create an image given `description`. The
`GotResponseWithImage` method will be called with the response text
and image URL as parameters:

```javascript
chatbot.GotResponseWithImage = (text, image) => {
  document.querySelector('img.output').src = image;
  document.body.appendChild(document.createTextNode(text));
}
chatbot.CreateImage("a cat with a hat");
```

If using the `async` syntax, a `Promise` to an object with the keys
`responseText` and `responseImage` is returned that can be `await`ed:

```json
{
  "responseText": "Okay, here's an image of...",
  "responseImage": "data:image/png;base64,AAeAF9VF1IFFEYP..."
}
```