@worktango/ai-assistant 0.0.1 → 0.0.2-beta-gd2

package/package.json

@@ -1,38 +1,63 @@
 {
   "name": "@worktango/ai-assistant",
-  "version": "0.0.1",
-  "main": "dist/ai-assistant.umd.js",
-  "module": "dist/ai-assistant.es.js",
-  "types": "react.d.ts",
+  "version": "0.0.2-beta-gd2",
   "files": [
-    "dist/*",
-    "react.js",
-    "react.d.ts",
+    "backendTypes.ts",
+    "constants.js",
+    "dist",
+    "express.d.ts",
     "express.js",
-    "express.d.ts"
+    "generated",
+    "react.d.ts",
+    "react.js",
+    "sharedTypes.ts"
   ],
   "scripts": {
-    "checkIfPublishable": "git status --porcelain | grep . && echo 'Dirty tree. Aborting.' && exit 1 || exit 0",
     "dev": "vite --config vite.config.ts src/dev",
     "dev:backend": "nodemon express.js",
-    "build:backend": "esbuild src/backend/express.ts --bundle --platform=node --outfile=dist/express.js \"--external:*\"",
+    "build:backend": "esbuild src/backend/express.ts --bundle --platform=node --outfile=dist/express.js \"--external:express\"",
     "build:frontend": "vite build",
-    "build": "yarn build:backend && yarn build:frontend && yarn ts-node -T scripts/injectCss.ts",
-    "prepareForPublish": "yarn ts-node -T scripts/prepareForPublish.ts",
-    "prepublishOnly": "yarn checkIfPublishable && rm -rf dist && yarn build",
-    "publish": "yarn prepareForPublish && yarn npm publish --access public --tolerate-republish; git reset --hard HEAD"
+    "build:all": "rm -rf dist && yarn build:backend && yarn build:frontend && yarn ts-node -T scripts/injectCssIntoBuild.ts",
+    "prepareBuildForPublish": "yarn ts-node -T scripts/prepareBuildForPublish.ts",
+    "publish": "yarn build:all && yarn prepareBuildForPublish && yarn actuallyPublishPackage",
+    "actuallyPublishPackage": "yarn npm publish --access public --tolerate-republish",
+    "gql:generate": "gql-generate",
+    "link:pulse-web": "bash scripts/linkToPulseWeb.sh"
   },
   "dependencies": {
-    "express": "4.21.2",
-    "react": "18"
+    "@apollo/client": "^3.0.0",
+    "@ricky0123/vad-react": "^0.0.28",
+    "@sinclair/typebox": "^0.34",
+    "apexcharts": "^4.7.0",
+    "classnames": "^2.2.6",
+    "dom-to-semantic-markdown": "^1.3",
+    "html2canvas": "^1.4.1",
+    "http-proxy-middleware": "^3",
+    "json-nd": "^1",
+    "lodash.clonedeep": "^4",
+    "micromark": "^4",
+    "micromark-extension-gfm-table": "^2.1.1",
+    "react-apexcharts": "^1.7.0",
+    "uuid": "^9"
   },
   "devDependencies": {
-    "@types/react": "^18",
     "@vitejs/plugin-react": "^4.2.1",
     "esbuild": "^0.17.11",
-    "ts-node": "^10.9.1",
-    "typescript": "~5.6",
-    "vite": "~6.2.4",
-    "vite-plugin-css-modules": "0.0.1"
+    "ts-node": "^10.9.2",
+    "typescript": "~5.8",
+    "vite": "~6.3.5"
+  },
+  "graphqlCodeGeneration": {
+    "apiHooks": {
+      "config": {
+        "enumsAsTypes": true
+      }
+    }
+  },
+  "$schema": "../../packages/build-tools/schema.json",
+  "peerDependencies": {
+    "express": ">=4",
+    "react": ">=18",
+    "react-dom": ">=18"
   }
 }

package/react.d.ts

@@ -0,0 +1,215 @@
+import type { TSchema, Type, Static } from "@sinclair/typebox";
+import {
+  AiAssistantProps,
+  ChatData,
+  ChatItem,
+  GetChatCompletionOptions,
+  GetStructuredResponseOptions,
+  ToolDeclaration,
+  AiAssistantSuggestedPromptsProps,
+  GetFollowUpSuggestions,
+  ChatDataFile,
+} from "./sharedTypes";
+
+export const getDefaultGetFollowUpSuggestions: (args: {
+  promptOverride?: string;
+}) => GetFollowUpSuggestions;
+
+export function AiAssistant(args: AiAssistantProps): JSX.Element;
+
+export function AiAssistantSuggestedPrompts(
+  args: AiAssistantSuggestedPromptsProps
+): JSX.Element;
+
+/**
+ * IMPORTANT: These types must be kept in sync with the source files:
+ * - AiResponseRating and GenAIRatingComponentProps are defined in src/frontend/components/GenAIRatingComponent.tsx
+ * - GenAIRatingComponentApolloWrappedProps is defined in src/frontend/components/GenAIRatingComponentApolloWrapped.tsx
+ *
+ * When updating these types in the source, you MUST also update them here.
+ */
+
+export interface AiResponseRating {
+  id: string;
+  userRating?: "THUMBS_UP" | "THUMBS_DOWN" | null;
+  userComment?: string | null;
+}
+
+export interface GenAIRatingComponentProps {
+  responseType: "WTC_MESSAGE" | "SURVEY_SUMMARY" | "COMMENTS_SUMMARY";
+  responseId: string;
+  genAiMessage: string;
+  genAiMessageTimestamp: string;
+  onSubmitRating: (input: any) => Promise<any>;
+  isLoading?: boolean;
+  error?: Error;
+  aiResponseRating?: AiResponseRating | null;
+}
+
+export type GenAIRatingComponentApolloWrappedProps = Omit<
+  GenAIRatingComponentProps,
+  "onSubmitRating" | "isLoading" | "error" | "aiResponseRating"
+> & {
+  /**
+   * Optional CSS value for the top position of success/error toasts.
+   *
+   * Use this to position toasts below fixed headers or other UI elements that might
+   * obscure them. Accepts any valid CSS top value (e.g., "80px", "5rem", "10%").
+   *
+   * @example
+   * // Position toasts 80px from the top, below a fixed admin header
+   * <GenAIRatingComponentApolloWrapped
+   *   responseType="WTC_MESSAGE"
+   *   responseId={id}
+   *   genAiMessage={message}
+   *   genAiMessageTimestamp={timestamp}
+   *   toastTop="80px"
+   * />
+   *
+   * @default undefined (uses the default toast position from Confetti)
+   */
+  toastTop?: string;
+};
+
+export function GenAIRatingComponent(
+  args: GenAIRatingComponentProps
+): JSX.Element;
+
+export function GenAIRatingComponentApolloWrapped(
+  args: GenAIRatingComponentApolloWrappedProps
+): JSX.Element;
+
+export const tools: {
+  kazooTools: {
+    getRewardsAndRecognitionCurrentUserTool: ToolDeclaration;
+  };
+  sharedTools: {
+    doMathTool: ToolDeclaration;
+    getCurrentTimeTool: ToolDeclaration;
+    askSingleShotQuestion: ToolDeclaration;
+    analyzeCurrentPage: ToolDeclaration;
+  };
+  /**
+   * Helper function to define a new tool for the AI Assistant.
+   *
+   * The tool's name, description, and the full schema of its parameters (including
+   * their descriptions) are sent to the LLM at the beginning of every interaction.
+   * The LLM uses this information to understand what the tool does and decide
+   * when and how to call it.
+   *
+   * Providing a clear, descriptive tool `description` and detailed descriptions
+   * for each field in the `parameters` object is essential for reliable tool calling.
+   */
+  createTool<TParams extends TSchema = TSchema>(args: {
+    name: string;
+    /**
+     * A description of the tool that is provided to the LLM.
+     * This tells the LLM what the tool is capable of getting or doing, helping it
+     * decide when to invoke it.
+     */
+    description: string;
+    /**
+     * A user-friendly, present-tense name for the tool (e.g., "Performing calculations").
+     * This is shown in the AI Assistant UI while the tool is executing.
+     */
+    displayName: string;
+    /**
+     * A user-friendly, past-tense name for the tool (e.g., "Performed calculations").
+     * This is shown in the AI Assistant's debug mode after the tool has finished executing.
+     */
+    pastTenseDisplayName: string;
+    /**
+     * A function that returns a JSON schema (using TypeBox) defining the arguments
+     * required by the tool. Each field in the schema should include a `description`
+     * to help the LLM provide accurate values.
+     */
+    parameters?: (t: typeof Type) => TParams;
+    /**
+     * The implementation function for the tool. This is called when the LLM
+     * decides to invoke the tool.
+     */
+    fulfill: (args: Static<TParams>) => Promise<string | ChatDataFile>;
+    /**
+     * Currently unused. Investigate intent and potential removal before using.
+     */
+    chatItemMatches?: (chatItem: ChatItem) => boolean;
+  }): ToolDeclaration;
+} = {};
+
+export const config: {
+  /**
+   * Get the URL for the LLM call.
+   */
+  getLlmCallUrl: () => string;
+  /**
+   * Get the URL for the structured response call.
+   */
+  getStructuredResponseUrl: () => string;
+  /**
+   * Get the URL for the Kazoo service.
+   */
+  getKazooUrl: (urlPath: string) => string;
+  /**
+   * Get the URL for the Pulse service.
+   */
+  getPulseUrl: (urlPath: string) => string;
+  /**
+   * Get the Pulse bearer token.
+   */
+  getPulseBearerToken: () => string;
+  /**
+   * Set the strategy for getting Kazoo URLs.
+   */
+  setKazooUrlStrategy: (strategy: (urlPath: string) => string) => void;
+  /**
+   * Set the strategy for getting LLM call URLs.
+   */
+  setLlmCallUrlStrategy: (strategy: (path: string) => string) => void;
+  /**
+   * Set the strategy for getting Pulse URLs.
+   */
+  setPulseUrlStrategy: (strategy: (urlPath: string) => string) => void;
+  /**
+   * Set the strategy for getting Pulse bearer tokens.
+   */
+  setPulseBearerTokenStrategy: (strategy: () => string) => void;
+  /**
+   * Set the strategy for getting structured response URLs.
+   */
+  setStructuredResponseUrlStrategy: (
+    strategy: (path: string) => string
+  ) => void;
+  /**
+   * Set the main content selector for the page for when taking screenshots.
+   */
+  setScreenshotMainContentSelector: (selector: string) => void;
+  /**
+   * Get the main content selector for the page for when taking screenshots.
+   */
+  getScreenshotMainContentSelector: () => string;
+  /**
+   * Set the strategy for getting synthesize URLs.
+   */
+  setSynthesizeUrlStrategy: (strategy: () => string) => void;
+  /**
+   * Set the strategy for getting transcribe URLs.
+   */
+  setTranscribeUrlStrategy: (strategy: () => string) => void;
+} = {};
+
+/**
+ * Makes a structured response request to the LLM API.
+ */
+export function getStructuredResponse<T extends TSchema>(
+  args: GetStructuredResponseOptions<T>
+): Promise<Static<T>>;
+
+/**
+ * Makes a chat completion request to the LLM API. Can be used both with streaming and non-streaming responses.
+ * For streaming responses, provides callbacks for handling chunks and errors.
+ */
+export function getChatCompletion(
+  args: GetChatCompletionOptions
+): Promise<ChatData[]>;
+
+export * from "./sharedTypes";

package/react.js

@@ -1 +1,4 @@
-export { AiAssistant } from "./dist/react.es.js";
+// istanbul ignore file - for public bundles only
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+module.exports = require("./dist/react.umd.js");

package/sharedTypes.ts

@@ -0,0 +1,386 @@
+// Don't import from the generated folder, as it is removed when we build and publish the package.
+
+import type { Static, TSchema, Type } from "@sinclair/typebox";
+
+export type Maybe<T> = T | undefined;
+export interface Scalars {
+  ID: string;
+  String: string;
+  Boolean: boolean;
+  Int: number;
+  Float: number;
+  Upload: any;
+  /** All dates within this schema are ISO-8601 strings without time or timezone. */
+  Date: any;
+  /** All date-times are supposed to be are ISO-8601 strings, but we do accept input in other formats.  That behavior will change and we will replace Date and DateTime's behavior with that of StrictDate. */
+  DateTime: any;
+  /** A datetime input and output type only accepts ISO-8601 dates. */
+  StrictDateTimeInput: string;
+  /** General-use Upload input scalar */
+  FileToUpload: any;
+  /** General-use scalar to use for fields of JSON data. See https://www.npmjs.com/package/graphql-type-json for more information. */
+  JSONObject: any;
+  /** Represents a rich text document in its native ProseMirror document format. This is a JSON object with a specific schema. Use a TipTap editor instance from the @kazoohr/richtext-components package to interact with this format. */
+  RichTextDocument: any;
+}
+
+export type AiAssistantConversationMessageRole =
+  /** A message that was sent by the LLM */
+  | "MODEL"
+  /** A message comes from tool calling. */
+  | "TOOL"
+  /** A message that was sent by the user. */
+  | "USER";
+
+export interface Message {
+  __typename?: "Message";
+  /** The unique identifier of the message. */
+  id: Scalars["ID"];
+  /** The role of the message. */
+  role: AiAssistantConversationMessageRole;
+  /** The text content of the message. */
+  messageText: Scalars["String"];
+  /** The conversation that the message belongs to. */
+  conversationId: Scalars["String"];
+  /** Optional metadata for the message to store such as toolNames etc */
+  metadata?: Maybe<Scalars["JSONObject"]>;
+}
+
+export type AiAssistantSuggestedPromptsProps = {
+  suggestedPrompts: Record<string, AiAssistantSuggestedPrompt[]>;
+  onSelect: (prompt: AiAssistantSuggestedPrompt) => void | Promise<void>;
+  includeGlobalPrompts?: boolean;
+};
+
+export type AiAssistantSuggestedPrompt = {
+  title: string;
+  fullPrompt?: string;
+  // Allow customization of the suggested action button in the UI
+  className?: string;
+};
+
+export type SupportedTextModel = "small" | "medium" | "large";
+
+export type ChatItem = {
+  role: "user" | "model" | "tool";
+  parts: ChatData[];
+};
+
+export type ToolDeclaration<TParams extends TSchema = TSchema> = {
+  name: string;
+  description: string;
+  /**
+   * A user-friendly, present-tense name for the tool (e.g., "Performing calculations").
+   * This is shown in the AI Assistant UI while the tool is executing.
+   */
+  displayName: string;
+  /**
+   * A user-friendly, past-tense name for the tool (e.g., "Performed calculations").
+   * This is shown in the AI Assistant's debug mode after the tool has finished executing.
+   */
+  pastTenseDisplayName: string;
+  parameters?: any;
+  /**
+   * Currently unused. Investigate intent and potential removal before using.
+   */
+  chatItemMatches?: (chatItem: {
+    role: "user" | "model" | "tool";
+    parts: ChatData[];
+  }) => boolean;
+  fulfill: (result: Static<TParams>) => Promise<string | ChatDataFile>;
+};
+
+/**
+ * Debug info added during the execution of the AI assistant.
+ */
+export type DebugInfo = {
+  time: Date;
+  message: string;
+  data?: any;
+  level: "info" | "error" | "warn";
+}[];
+
+export type PropRefs = {
+  onAfterLlmCall?: (messages: Omit<Message, "__typename">[]) => void;
+  onBeforeLlmCall?: () => void;
+  onError?: (error: Error) => void;
+  onChunkAdded?: () => void;
+  tools?: ToolDeclaration[];
+  model?: SupportedTextModel;
+  /**
+   * The current state of the chat.
+   *
+   * When to access this:
+   * - When you're in async handler functions
+   * - When you're in callbacks
+   *
+   * When NOT to access this:
+   * - When you're in anywhere in the UI state rendering path
+   *
+   * If you're rendering the UI, use the `messages` prop, please. This is for
+   * AI assistant state, which often requires up-to-date state for making
+   * updates.
+   */
+  messages: ChatStateTree;
+  temperature?: number;
+  isMounted: boolean;
+  systemInstruction?: () => string | Promise<string>;
+  getConversationById: (
+    conversationId: string
+  ) => ChatStateTree[string] | undefined;
+  getFollowUpSuggestions?: GetFollowUpSuggestions;
+  setFollowUpSuggestionsByConversationId: React.Dispatch<
+    React.SetStateAction<Record<string, FollowUpSuggestion[]>>
+  >;
+  handleSendUserMessage: (args: {
+    conversationId?: string;
+    messageText: string;
+  }) => Promise<void>;
+  setPrompt: (
+    conversationId: string | undefined,
+    prompt: string | ((prev: string) => string)
+  ) => void;
+  onSelectedConversationChange?: (
+    conversationId: string | undefined,
+    messages: ChatStateTree
+  ) => void;
+  selectedConversationId: string | undefined;
+  onSelectedConversationLoaded?: (
+    /**
+     * The conversation that loaded.
+     */
+    conversationId: string | undefined,
+    /**
+     * The conversation that is currently selected
+     */
+    selectedConversationId: string | undefined,
+    messages: ChatStateTree
+  ) => void;
+  sendMessages: (conversationId: string) => Promise<boolean>;
+  setMessages: React.Dispatch<React.SetStateAction<ChatStateTree>>;
+};
+
+export type ChatData =
+  | ChatDataText
+  | ChatDataToolCall
+  | ChatDataToolResult
+  | ChatDataFile;
+
+export type ChatDataText = { type: "text"; text: string };
+
+export type ChatDataFile = {
+  type: "file";
+  toolName: string;
+  fileUri: string;
+  mimeType: string;
+  args?: unknown;
+};
+
+export type ChatDataToolCall = {
+  type: "toolCall";
+  toolName: string;
+  args: Record<string, unknown>;
+};
+
+export type ChatDataToolResult = {
+  type: "toolResult";
+  toolName: string;
+  args?: unknown;
+  result: any;
+};
+
+export type ChatHistoryItem = {
+  title: string;
+  messages: any[];
+  [key: string]: any;
+};
+
+export type GetFollowUpSuggestions = (args: {
+  conversation: ChatStateTree[string];
+}) => Promise<AiAssistantSuggestedPrompt[]>;
+
+export type ChatHistory = Record<string, ChatHistoryItem[]>;
+
+export type ChatSizes = "half" | "full";
+
+export type AiAssistantControls = {
+  /**
+   * Set the prompt to use for the AI assistant.
+   * @param prompt - The prompt to set.
+   * @param submit - Whether to submit the prompt to the AI assistant once the new prompt is set.
+   */
+  setPrompt?: (prompt: string, submit?: boolean) => void;
+};
+
+export type AiAssistantProps = {
+  /**
+   * The title to display in the window. Default: "WorkTango AI Assistant".
+   */
+  windowTitle?: React.ReactNode;
+  /**
+   * The full suite of tools to use for the AI assistant.
+   */
+  tools?: ToolDeclaration<any>[];
+  /**
+   * Whether to enable debug mode. Default: false.
+   */
+  enableDebug?: boolean;
+  /**
+   * Whether to enable voice features. Default: false.
+   */
+  enableVoiceFeatures?: boolean;
+  /**
+   * The function to call when the AI assistant is closed.
+   */
+  onClose: () => void;
+  /**
+   * This is a callback event that is invoked when the user sends a message.
+   */
+  onSendMessage?: (message: string) => void;
+  /**
+   * Whether to show a close button in the chat window. Default: true.
+   */
+  hasCloseButton?: boolean;
+  /**
+   * The zero state to display when the chat window is empty.
+   */
+  chatWindowZeroState?: React.ReactNode;
+  /**
+   * Whether to show a button to toggle the chat size. Default: true.
+   */
+  hasToggleChatSizeButton?: boolean;
+  /**
+   * If true, the chat history (list of past conversations) will be shown, by default
+   */
+  hasChatHistory?: boolean;
+  /**
+   * The initial width of the chat window. Default: "default".
+   */
+  startingWidth?: ChatSizes;
+  /**
+   * The system instruction to use for the AI assistant.
+   */
+  systemInstruction?: () => string | Promise<string>;
+  /**
+   * The initial prompt to use for the AI assistant.
+   */
+  initialPrompt?: string;
+  /**
+   * A ref to the controls object for the AI assistant. Used to allow some form
+   * of control over the AI assistant from outside the component, allowing things
+   * like recommended prompts to be set from outside the component.
+   */
+  controls?: React.MutableRefObject<AiAssistantControls>;
+  /**
+   * Whether to show the chat history by default. Default: true.
+   */
+  chatHistoryShownByDefault?: boolean;
+  /**
+   * Otherwise, if there's a chat history, we start with the latest history, so
+   * the user can continue the previous conversation.
+   */
+  startWithNewChat?: boolean;
+  /**
+   * The minimum number of characters that must be entered before the user can
+   * submit a message. Default: 5.
+   */
+  minimumCharacterCount?: number;
+  /**
+   * The ID of the conversation to start with. If not provided, a new conversation will be created.
+   */
+  initialConversationId?: string;
+  /**
+   * Returns a set of follow-up suggestions for the given conversation.
+   */
+  getFollowUpSuggestions?: GetFollowUpSuggestions;
+  /**
+   * Invoked with a raw string of the chat (in plain text) to get a possible title
+   */
+  getChatTitle?: (chat: string) => Promise<string>;
+  /**
+   * The model size to use for the AI assistant. Default: "large".
+   */
+  model?: SupportedTextModel;
+  /**
+   * Whether to enable the AI response rating component. Default: false.
+   * Cannot bundle feature-flags-react in packages/ai-assistant so this is how we have to pass feature flags to the Ai Assistant.
+   */
+  enableResponseRating?: boolean;
+};
+
+export type ChatStateTree = Record<
+  string,
+  {
+    id: string;
+    title: string;
+    isUpdatingTitle?: boolean;
+    updatedAt: Date;
+    isLoading: boolean;
+    messages: Omit<Message, "__typename">[];
+  }
+>;
+
+// ChatItem augmented with some UI stuff
+export type AugmentedChatItem = ChatItem & {
+  id?: string;
+  timestamp?: Date;
+  isPending?: boolean;
+  filterFromApiCalls?: boolean;
+};
+
+/**
+ * If { loading: true }, a small loader will be shown. You can use this show a
+ * loading state in any place of the UI.
+ */
+export type FollowUpSuggestion =
+  | { type: "loading"; id?: string }
+  | {
+      type?: "suggestion";
+      /**
+       * A unique identifier for the follow-up suggestion. This will be used to keep user-level state for dismissed items.
+       */
+      id: string;
+      /**
+       * The title of the follow-up suggestion. This will be displayed in the UI as a pill button, so keep it short.
+       */
+      title: string;
+      /**
+       * The function to call when the follow-up suggestion is clicked.
+       */
+      onClick: () => void;
+      /**
+       * Optional CSS class name for custom styling of the pill.
+       */
+      className?: string;
+    };
+
+export interface Conversation {
+  id: string;
+  title: string;
+  updatedAt?: Date;
+  messages: {
+    conversationId: string;
+    id: string;
+    messageText: string;
+    role: string;
+  }[];
+}
+
+export type GetStructuredResponseOptions<T extends TSchema> = {
+  model?: SupportedTextModel | undefined;
+  temperature?: number | undefined;
+  prompt: string;
+  schema: (t: typeof Type) => T;
+};
+
+export type GetChatCompletionOptions = {
+  model?: SupportedTextModel | undefined;
+  temperature?: number | undefined;
+  systemInstruction?: string | undefined;
+  stream?: boolean;
+  messages: ChatItem[];
+  tools?: ToolDeclaration[] | undefined;
+  onChunk?: (chunk: ChatData) => void;
+  onError?: (error: Error) => void;
+  onComplete?: () => void;
+};