# AI Assistant

A React component for embedding the WorkTango AI Assistant in your web application.

In scope:
- Voice to text, text to voice, and text-only chat interfaces
- Single-stream back-and-forth UI between an LLM and a user, similar to popular LLM AI assistant UIs
- Standardized API for consumers to hook into the chat and provide new guidance for the session, add instructions, contextual information, and other things to make the assistant more useful, or tailored to a specific feature or user
- Standardized API for tool calls, with multiple layers of fulfillment (e.g., client fulfilled; sourceServerFulfilled; proxyServerFulfilled)
- Consistent styling across WorkTango apps
- Embeddable in any React application
- Consistent with our other React components

Out of scope (for now):
- Chat session history management
- User authentication (we provide a server-to-server proxy middleware for that; this should only work for logged-in users)
- Unauthenticated users and LLM sessions (low chance we will ever even need this)
- Anything else not explicitly mentioned in the scope section, above

## Installation

```bash
npm install @worktango/ai-assistant
# or
yarn add @worktango/ai-assistant
```

## Usage

### Code generation

Our normal code generation can be used in this API, but with one caveat: this package may not use the normal GraphQL hooks when fulfilling tool calls. (You may still use hooks to do other operations, like upload metadata, chat history, etc.) Instead, use the `packages/ai-assistant/src/frontend/tools/generatedSdks.ts` map to access our strongly-typed SDKs.

For more information on code generation, see the [GraphQL README](../graphql/README.md).

In short:

1. Add the package you want to query to `dependencies` in this package
2. Write the appropriate query in this package's `queries` directory
3. Run `yarn generate:gql`.

Your generated code will be in `packages/ai-assistant/generated`.

Also note that _we commit generated files_, since they are path agnostic and have saved hundreds of hours of build times over the years.

### React Applications

```jsx
import { AiAssistant } from "@worktango/ai-assistant/react";
import "@worktango/ai-assistant/dist/ai-assistant.css";

function App() {
  return (<AiAssistant />);
}
```

**Note:** You must import the CSS file to ensure components are styled correctly. This includes components like `GenAIRatingComponentApolloWrapped`.

### Using GenAIRatingComponentApolloWrapped

The `GenAIRatingComponentApolloWrapped` component allows users to rate AI-generated content (e.g., survey summaries, comments summaries). It can be used outside the AI Assistant context.

**Important:** You must configure the bearer token strategy before using this component. This is typically done once at your app's initialization:

```tsx
import { config } from "@worktango/ai-assistant/react";
import { getAccessToken } from './your-auth-module';

// In your root component or app initialization
React.useEffect(() => {
  config.setPulseBearerTokenStrategy(() => getAccessToken() ?? '');
}, []);
```

Once configured, you can use the component anywhere in your app:

```tsx
import { GenAIRatingComponentApolloWrapped } from "@worktango/ai-assistant/react";
import "@worktango/ai-assistant/dist/ai-assistant.css";

function MyComponent() {
  return (
    <GenAIRatingComponentApolloWrapped
      responseType="SURVEY_SUMMARY"
      responseId="123"
      genAiMessage="This is the AI-generated summary..."
      genAiMessageTimestamp="2026-01-28T12:00:00Z"
      aiResponseRating={existingRating} // Optional: existing rating data
    />
  );
}
```

## Testing

To test whether a change might break the build when this application is deployed on another server, you can test it in this repository in the following ways:

**Testing just the UI**

If you just made UI changes, you can rename `packages/ai-assistant/react.ts` to `_react.ts`; and `react.public.js` to `react.js`. Then, run `yarn build:all` in this package. Once you do that, when you restart the development server, webpack will use the `react.js` file to load the component over at `/admin/ai-assistant`, and use the fully bundled React component to do so.

**Testing locally with pulse-web**

To test changes in pulse-web before publishing to npm, use `yarn link`:

1. **Register the package for linking in kazoo-web:**
   ```bash
   cd /path/to/kazoo-web/packages/ai-assistant
   yarn link
   ```
   
   This registers `@worktango/ai-assistant` globally for linking.

2. **Link the package in pulse-web:**
   ```bash
   cd /path/to/pulse-web
   yarn link @worktango/ai-assistant
   ```
   
   This creates a symlink from pulse-web's `node_modules` to your local kazoo-web package.

3. **Build the package after making changes:**
   
   After any code changes in kazoo-web:
   ```bash
   cd /path/to/kazoo-web/packages/ai-assistant
   yarn build:all
   ```
   
   Restart your pulse-web dev server to pick up the changes.

4. **When done testing:**
   
   Unlink the package in pulse-web:
   ```bash
   cd /path/to/pulse-web
   yarn unlink @worktango/ai-assistant
   yarn install --force
   ```
   
   This removes the symlink and reinstalls the published version from npm.

## Features

- Unified tool call API for all WorkTango apps