@smarter.sh/ui-chat 0.3.0 → 0.7.0

package/LICENSE

@@ -660,9 +660,9 @@ if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU AGPL, see
 <http://www.gnu.org/licenses/>.
 
-EdX Inc. wishes to state, in clarification of the above license terms, that
+Lawrence McDaniel wishes to state, in clarification of the above license terms, that
 any public, independently available web service offered over the network and
-communicating with edX's copyrighted works by any form of inter-service
+communicating with Lawrence McDaniel's copyrighted works by any form of inter-service
 communication, including but not limited to Remote Procedure Call (RPC)
 interfaces, is not a work based on our copyrighted work within the meaning
 of the license. "Corresponding Source" of this work, or works based on this

package/README.md

@@ -1,225 +1,178 @@
 [![NPM](https://a11ybadges.com/badge?logo=npm)](https://www.npmjs.com/package/@smarter.sh/ui-chat)
 [![GitHub](https://a11ybadges.com/badge?logo=github)](https://github.com/smarter-sh/smarter-chat/)
+[![Test Status](https://github.com/smarter-sh/smarter-chat/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/smarter-sh/smarter-chat/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/smarter-sh/smarter-chat/main?label=coverage&logo=codecov)](https://codecov.io/gh/smarter-sh/smarter-chat)
 <a href="https://smarter.sh">
 <img src="https://img.shields.io/badge/Smarter.sh-orange?style=flat&logo=appveyor&logoColor=white" height="32">
 </a>
 
-# SmarterChat React.js component for smarter.sh
-
-This project contains the source code for the interactive chatbot found in the Smarter web console [developer workbench](https://platform.smarter.sh/chatbots/example/). It integrates natively with Smarter Saas and on-premise installations. You can optionally enable the meta data output behavior found in the Smarter sandbox. See [Smarter Technical Overview](./doc/README.md)
-
-This project is also suitable for all front-end cross-platform projects. For example, use this code base to create a react.js run-time for use inside of Wordpress plugins, salesforce.com apps, .net components and Sharepoint add-ins.
+# Smarter Chat
+
+Smarter Chat is the React chat component of the [Smarter](https://smarter.sh) LLMClient prompt engineering
+workbench. Beside the chat, its Console displays the LLMClient's configuration, and the chat session's api calls,
+tool calls and plugin usage, and optionally streams your server logs, in color, with long lines that scroll or wrap.
+Drag the separator between the chat and the Console to resize them, or hide the Console, which slides out to the right.
+The new chat button starts a new chat session, and clears the server logs. The Sandbox mode / Production mode button
+shows and hides the backend's own messages in the chat thread. While a prompt runs, its progress (LLM requests, tool,
+plugin and MCP server calls) is displayed in the thread, and a failed prompt is displayed with the LLM provider's error
+message. Responses are rendered as GitHub flavored markdown (headings, emphasis, lists, tables, block quotes, code,
+links and images), with raw html escaped, and images are scaled to fit their chat bubble. Math, written in LaTeX as
+`\( ... \)` inline, or `\[ ... \]` or `$$ ... $$` displayed, is typeset by [KaTeX](https://katex.org). A `mermaid` code block is drawn as a
+[Mermaid](https://mermaid.js.org) diagram, which is downloaded only when a message first has one, with a button that
+shows its code.
+
+It is also published to npm as [@smarter.sh/ui-chat](https://www.npmjs.com/package/@smarter.sh/ui-chat), so that
+any web page can use a Smarter LLMClient as its chat backend: a Wordpress or Squarespace site, a Salesforce portal,
+a Shopify storefront, a Sharepoint add-in, or your own web application.
 
 ![Basic Usage](./doc/img/readme-usage4.png)
 
-## Usage
+See the [Smarter Chat documentation](https://docs.smarter.sh/en/latest/smarter-framework/developer-reference/react-integration/smarter-chat.html).
 
-Generic usage of the published npm package is as follows
+## Usage
 
 ```console
 npm install @smarter.sh/ui-chat
 ```
 
-```jsx
-import React from "react";
-import ReactDOM from "react-dom/client";
+```tsx
+import { createRoot } from "react-dom/client";
 import { SmarterChat } from "@smarter.sh/ui-chat";
-
-const rootElement = document.getElementById("smarter-sh-v1-ui-chat-root");
-const root = ReactDOM.createRoot(rootElement);
-const apiUrl = rootElement.getAttribute("smarter-chatbot-api-url") || "http://localhost:9357/api/v1/chatbots/1/";
-const toggleMetadata = rootElement.getAttribute("smarter-toggle-metadata") === "true";
-const csrfCookieName = rootElement.getAttribute("smarter-csrf-cookie-name") || "csrftoken";
-const sessionCookieName = rootElement.getAttribute("smarter-session-cookie-name") || "session_key";
-const cookieDomain = rootElement.getAttribute("smarter-cookie-domain") || "localhost";
-const authSessionCookieName = rootElement.getAttribute("django-session-cookie-name") || "sessionid";
-const csrftoken = rootElement.getAttribute("django-csrftoken");
-const debugMode = rootElement.getAttribute("smarter-debug-mode") === "true";
-const debugCookieName = "debug";
-
-root.render(
-  <React.StrictMode>
-    <SmarterChat
-      apiUrl={apiUrl}
-      apiKey={apiKey}
-      toggleMetadata={toggleMetadata}
-      csrfCookieName={csrfCookieName}
-      csrftoken={csrftoken}
-      debugCookieName={debugCookieName}
-      debugCookieExpiration={debugCookieExpiration}
-      debugMode={debugMode}
-      sessionCookieName={sessionCookieName}
-      sessionCookieExpiration={sessionCookieExpiration}
-      authSessionCookieName={authSessionCookieName}
-      showConsole={true}
-      cookieDomain={cookieDomain}
-    />
-  </React.StrictMode>,
+import "@smarter.sh/ui-chat/dist/ui-chat.css";
+// the stylesheet and fonts of math in the responses. katex is installed with @smarter.sh/ui-chat.
+import "katex/dist/katex.min.css";
+
+createRoot(document.getElementById("chat")!).render(
+  <SmarterChat
+    apiUrl="https://stackademy.3141-5926-5359.api.example.com/"
+    cookieDomain="example.com"
+    showConsole={false}
+  />,
 );
 ```
 
-### Build from source
+React 19 is a peer dependency.
 
-To build and deploy for use in the Smarter Web Console Prompt Engineer Workbench, do the following.
-This assumes that you have already built your AWS cloud infrastructure using [github.com/smarter-sh/smarter-infrastructure](https://github.com/smarter-sh/smarter-infrastructure) and that a CDN exists at cdn.platform.example.com.
+### Props
 
-```console
-export ROOT_DOMAIN=example.com
-export PLATFORM_SUBDOMAIN=platform
-npm install
-make build
-make release
-```
+| Prop                      | Default         | Description                                                                                             |
+| ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
+| `apiUrl`                  | (required)      | The url of the LLMClient's api. The chat appends `config/` for its configuration.                       |
+| `apiKey`                  | `null`          | A Smarter api key, sent as `Authorization: Token <apiKey>`, for LLMClients that require authentication. |
+| `toggleMetadata`          | `false`         | Show the button that shows and hides the backend's messages (system prompt, tool results, Smarter's).   |
+| `showConsole`             | `true`          | Show the Console beside the chat. It needs a wide page.                                                 |
+| `debugMode`               | `false`         | Log to the browser console.                                                                             |
+| `csrfCookieName`          | `"csrftoken"`   | The name of Django's CSRF cookie, whose value is sent as the `X-CSRFToken` header.                      |
+| `csrftoken`               | `null`          | The CSRF token, when the page cannot read the CSRF cookie.                                              |
+| `sessionCookieName`       | `"session_key"` | The cookie in which the chat saves its chat session's key, for the page's path.                         |
+| `sessionCookieExpiration` | one day         | The session cookie's lifetime, in milliseconds.                                                         |
+| `debugCookieName`         | `"debug"`       | The cookie in which the chat saves the LLMClient's debug mode.                                          |
+| `debugCookieExpiration`   | one day         | The debug cookie's lifetime, in milliseconds.                                                           |
+| `cookieDomain`            | `""`            | The domain whose cookies the chat reads. Empty means the page's own domain.                             |
+| `smarterRequestId`        | `""`            | A unique id of the page request, sent as the `X-Smarter-RequestId` header.                              |
+| `streamProgress`          | `true`          | Display a running prompt's progress, which the prompt api streams as Server-Sent Events.                |
+| `logStreamUrl`            | `null`          | The url of a server log stream (Server-Sent Events), for the Console's "Server Logs" tab.               |
 
-## Integrate to an existing web page
+The package also exports the `Console` component, the `MessageDirectionEnum`, `SenderRoleEnum`,
+`ValidMessageRolesEnum` and `MenuItems` enums, `version`, and TypeScript types for its props and for the
+Smarter api's data (`SmarterChatProps`, `ChatConfig`, `ChatMessage`, `PromptProgressEvent`, ...).
 
-We integrate this react component to the [Smarter developer workbench](https://platform.smarter.sh/) using this small repo, [github.com/smarter-sh/web-integration-example](https://github.com/smarter-sh/web-integration-example). This methodology provides a layer of separation between Django and react.js, which keeps things simple. smarter-workbench substantially consists of the following three files:
+### The Smarter api
 
-- [main.jsx](https://github.com/smarter-sh/smarter-workbench/blob/main/src/main.jsx): a 40-line react.js mini app for configuring this npm component with a Smarter Api url and any initialization settings we choose to include.
-- [app-loader.js](https://github.com/smarter-sh/smarter-workbench/blob/main/src/public/app-loader.js): a small js script that injects the react.js build assets into your DOM, initiating the React boot-up process.
-- [Makefile](https://github.com/smarter-sh/smarter-workbench/blob/main/Makefile): for automating build and release to AWS Cloudfront, where the react ui-chat app is served.
+Smarter Chat calls two apis, both with POST requests that send the browser's cookies:
 
-Meanwhile, Django adds a pair of DOM elements like the following example, where app-loader.js launches itself with an "iffe", (Immediately Invoked Function Expression).
+- `<apiUrl>config/?session_key=<key>`: the LLMClient's configuration, including the chat session's history,
+  which restores the chat thread when the page reloads. A new chat session's key is saved in the session cookie.
+- `chatbot.url_chatbot` in the configuration: the LLMClient's prompt api. It receives the chat thread with each
+  new message, `{"session_key": "...", "messages": [...]}`, and returns the completion as a JSON string, in
+  `data.body`, whose `smarter.messages` are added to the thread. A failed prompt returns the LLM provider's status,
+  and `{"error": {"status", "message"}, "response": <the completion>}` in its body. With `streamProgress`, the
+  request accepts `text/event-stream`, and the response is `progress` events while the prompt runs, then a `result`
+  event, `{"status": <http status>, "response": <the same JSON>}`. A server that doesn't stream answers with JSON.
 
-```html
-<div
-  id="smarter-sh-v1-ui-chat-root"
-  smarter-chatbot-api-url="https://openai.3141-5926-5359.api.smarter.sh/"
-  smarter-toggle-metadata="False"
-  style="height: 88vh;"
-></div>
-<script async="" src="https://cdn.platform.smarter.sh/ui-chat/app-loader.js"></script>
-```
+Requests from your page to the Smarter api are cross-origin, so your page's origin must be allowed by the Smarter
+platform's CORS configuration.
 
-## Developers
+## Development
 
-SmarterChat is created with [React](https://react.dev/) leveraging [@chatscope/chat-ui-kit-react](https://www.npmjs.com/package/@chatscope/chat-ui-kit-react)
-
-### Setup
-
-1. Build your component
-
-   ```console
-   npm install -g yalc
-   npm run build
-   yalc publish
-   ```
-
-2. Create a separate test React app (outside your library folder)
+This repository is self-contained: clone it, and its Makefile does the rest. The Smarter backend is optional.
 
 ```console
-npx create-react-app smarter-chat-test
-cd smarter-chat-test
+git clone https://github.com/smarter-sh/smarter-chat.git
+cd smarter-chat
+make init    # npm install
+make serve   # Storybook, at http://localhost:6006
 ```
 
-3. Link your local package to the test app. This is a 1-time operation.
+`make serve` browses the components in Storybook, whose stories mock the Smarter api with
+[MSW](https://mswjs.io/), so no backend is needed. When the Smarter dev server is running at http://localhost:9357, the
+stories use the web console's own stylesheets; without it, they use Bootstrap, which the web console's theme is built
+on.
 
-```console
-yalc add @smarter.sh/ui-chat
-npm install # verifies peer dependencies
-```
+| Command         | What it does                                                                                      |
+| --------------- | ------------------------------------------------------------------------------------------------- |
+| `make init`     | Installs the dependencies.                                                                        |
+| `make serve`    | Browses the components in Storybook, with the Smarter api mocked.                                 |
+| `make run`      | Runs the app with Vite's dev server, proxying api requests to the Smarter dev server (port 9357). |
+| `make build`    | Builds the app, with a Vite manifest for Django, and the npm package into `dist/`.                |
+| `make test`     | Runs the unit tests (Vitest and React Testing Library). Every story is also rendered as a test.   |
+| `make coverage` | Runs the unit tests with a coverage report in `coverage/`, which CI uploads to Codecov.           |
+| `make lint`     | Lints with ESLint, type-checks with TypeScript, and checks formatting with Prettier.              |
+| `make release`  | Runs the tests, then builds the npm package into `dist/` and publishes it to npm.                 |
 
-4. In the test app, import and use your component as you described.
+### Inside the Smarter repository
 
-5. Start the test app
+Smarter's web console hosts Smarter Chat as one of the React apps in its npm workspace. `make react-install`, in the
+[Smarter repository](https://github.com/smarter-sh/smarter), clones this repository into
+`smarter/react/packages/smarter-chat`:
 
 ```console
-yalc update @smarter.sh/ui-chat
-npm run build
-npm start
+git clone https://github.com/smarter-sh/smarter.git
+cd smarter
+make react-install                            # clones smarter-chat's main branch
+make react-install SMARTER_CHAT_BRANCH=alpha  # or another branch
 ```
 
-### Backend integration
-
-See [Getting Started with the Smarter Chatbot Api](./doc/CHATBOT_API.md)
-This app interacts with two endpoints from the [smarter.sh/v1](https://platform.smarter.sh/docs/api/) chatbot api:
+The same `make` commands work there, in `smarter/react/packages/smarter-chat`, which is this repository's own git
+working tree. Two differ: `make init` installs the whole workspace's dependencies, and `make build` builds the app into
+the Smarter web console's static files, rather than into `build/`. The Smarter repository's `make react-test` and
+`make react-lint`, and its GitHub Actions workflows, also test and lint Smarter Chat along with the other React apps.
 
-- GET `/config/`: retrieves a json dict, structured in 4 major sections, with all information required by the react app.
-- POST `/chat/`: send a text completion prompt to the Smarter Api.
+### Commits, versions and releases
 
-Smarter chatbot urls use either of these two naming conventions:
+Run `make pre-commit-init` once per clone (the Smarter repository's `make react-install` does it when its virtual
+environment is active). It installs two git hooks: pre-commit, which runs codespell, Prettier and
+ESLint, and the standard pre-commit-hooks checks, and commit-msg, which runs commitlint.
 
-- public: `https://<name>.<account_number>.example.com/`
-- authenticated: `https://platform.smarter.sh/chatbots/<name>/`. This react component looks for and adds the Smarter platform sessionid cookie value to request headers, if it exists.
-
-Public api url example for a deployed chatbot:
-
-- `https://my-chatbot.3141-5926-5359.api.smarter.sh/config/`
-- `https://my-chatbot.3141-5926-5359.api.smarter.sh/chat/`
-
-Authenticated api url example for any chatbot in your Smarter account:
-
-- `https://platform.smarter.sh/chatbots/my-chatbot/config/`
-- `https://platform.smarter.sh/chatbots/my-chatbot/chat/`
-
-#### Config
-
-A Json dict containing all configuration data for the chatbot. This is downloaded at run-time when the reactapp is initializing.
-Example: [/chatbots/example/config/?session_key=YOUR-SESSION-KEY](http://localhost:8000/chatbots/example/config/)
-
-See: [sample config](./data/sample-config.json)
-
-#### Api
-
-A REST Api for sending and receiving chat prompt requests. The url comes from the config dict (above): data.chatbot.url_chatbot.
-example: `http://api.smarter.sh/v1/chatbots/smarter/example/`
-
-example http request:
-
-```json
-{
-    "method": "POST",
-    "credentials": "include",
-    "mode": "cors",
-    "headers": {
-        "Accept": "application/json",
-        "Content-Type": "application/json",
-        "X-CSRFToken": "q9WXqqIhYJMI3ZSBIOE18JMORBMqAHri",
-        "Origin": "http://localhost:8000",
-        "Cookie": "session_key=a07593ecfaecd24008ca4251096732663ac0213b8cc6bdcce4f4c043276ab0b5; debug=true;"
-    },
-    "body": "{\"session_key\":\"a07593ecfaecd24008ca4251096732663ac0213b8cc6bdcce4f4c043276ab0b5\",\"messages\":[{\"role\":\"system\",\"content\":\"You are a helpful chatbot."},{\"role\":\"assistant\",\"content\":\"Welcome to the Smarter demo!\"}]}"
-}
-```
-
-example http response:
-
-```json
-{
-  "data": {
-    "isBase64Encoded": false,
-    "statusCode": 200,
-    "headers": {
-      "Content-Type": "application/json"
-    },
-    "body": "{\"id\": \"chatcmpl-AoDpMvoAhf8iSJuEm6pMqkX62HK4G\", \"choices\": [{\"finish_reason\": \"stop\", \"index\": 0, \"logprobs\": null, \"message\": {\"content\": \"Hello! While I'm not your mom, I'm here to help you with any questions or tasks you have. What can I assist you with today?\", \"refusal\": null, \"role\": \"assistant\", \"audio\": null, \"function_call\": null, \"tool_calls\": null}}], \"created\": 1736532916, \"model\": \"gpt-4-turbo-2024-04-09\", \"object\": \"chat.completion\", \"service_tier\": \"default\", \"system_fingerprint\": \"fp_f17929ee92\", \"usage\": {\"completion_tokens\": 33, \"prompt_tokens\": 1122, \"total_tokens\": 1155, \"completion_tokens_details\": {\"accepted_prediction_tokens\": 0, \"audio_tokens\": 0, \"reasoning_tokens\": 0, \"rejected_prediction_tokens\": 0}, \"prompt_tokens_details\": {\"audio_tokens\": 0, \"cached_tokens\": 0}}, \"metadata\": {\"tool_calls\": null, \"model\": \"gpt-4-turbo\", \"temperature\": 0.5, \"max_tokens\": 256, \"input_text\": \"hi mom\"}}"
-  },
-  "api": "smarter.sh/v1",
-  "thing": "Chatbot",
-  "metadata": {
-    "command": "chat"
-  }
-}
-```
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/), as Smarter's do, because
+[semantic-release](https://semantic-release.gitbook.io/) versions this package from them. On each push to `alpha`
+(prereleases, e.g. `1.0.0-alpha.1`) and to `main`, `.github/workflows/pushMain.yml` determines the next version, writes
+it to `package.json`, adds the release notes to `CHANGELOG.md`, tags the commit and creates a GitHub release. A release
+on `main` is then merged back into `alpha`. `feat` commits are minor releases, `fix` and `perf` commits are patches, and
+a `BREAKING CHANGE:` footer is a major release. See `release.config.cjs`.
 
-## Contributor Reference
+semantic-release does not publish to npm. After a release on `main`, publish it with `make release`.
 
-### Getting Started
+### Source
 
-- `make`: prints a full menu of commands to the console.
-- `make init`: Setup your environment for first time use. sets up your Node environment for you. initializes pre-commit, which you need to run prior to creating pull requests.
-- `make run`: Run the dev server locally
-- `make build`: Build the react.js project. saves vite.js output to `./build` in the root of this project.
-- `make release`: Deploy the react.js project. **REQUIRES awscli + keypair with sufficient permissions**. Publishes the contents of the `./build` folder to an AWS S3 bucket served by the host defined by the value of `CDN_HOST_BASE_URL` located in shared/constant.js. For example, the react app for the Smarter workbench is initialized and served from these endpoints: a. [index.html](https://cdn.platform.smarter.sh/ui-chat/index.html): the react app build artifacts, and b. [app-loader.js](https://cdn.platform.smarter.sh/ui-chat/app-loader.js): a script to insert the react app build artifacts into the DOM.
+| Path                          | Contents                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `src/index.ts`                | The npm package's public api.                                                              |
+| `src/main.tsx`, `src/App.tsx` | The app that the Smarter web console renders, configured by its root element's attributes. |
+| `src/components/`             | `SmarterChat`, `Console`, `AppTitle` and `ErrorBoundary`, with their stories and tests.    |
+| `src/lib/`                    | The Smarter api calls, the chat thread's messages, and cookies.                            |
+| `src/mocks/`                  | Example api data and MSW handlers, for the stories and tests.                              |
 
-### Architecture
+## License
 
-- [Vite](https://vitejs.dev/)
-- [React](https://react.dev/)
-- [Chat UI Kit React](https://www.npmjs.com/package/@chatscope/chat-ui-kit-react)
+Smarter Chat is licensed under the GNU Affero General Public License v3.0 or later
+([AGPL-3.0-or-later](./LICENSE)), as Smarter is.
 
 ## Contributing
 
-We welcome contributions! There are a variety of ways for you to get involved, regardless of your background. In addition to Pull requests, this project would benefit from contributors focused on documentation and how-to video content creation, testing, community engagement, and stewards to help us to ensure that we comply with evolving standards for the ethical use of AI.
+We welcome contributions! There are a variety of ways for you to get involved, regardless of your background. In
+addition to Pull requests, this project would benefit from contributors focused on documentation and how-to video
+content creation, testing, community engagement, and stewards to help us to ensure that we comply with evolving
+standards for the ethical use of AI.
 
 You can also contact [Lawrence McDaniel](https://lawrencemcdaniel.com/contact) directly.