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

package/README.md

@@ -3,16 +3,18 @@
 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 unified backend integration
+- 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):
-- Previous chat management UI
+- 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
@@ -25,20 +27,119 @@ 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 (
-    <div>
-      <AiAssistant />
-    </div>
+    <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
 
-😄 none, yet!
+- Unified tool call API for all WorkTango apps

package/backendTypes.ts

@@ -0,0 +1,268 @@
+// Don't import from the generated folder, as it is removed when we build and publish the package.
+
+import type {
+  AppendMessageInput,
+  AppendMessageToConversationMutation,
+  ConversationInput,
+  CreateConversationInput,
+  DeleteConversationInput,
+  UpdateConversationTitleInput,
+  GetAConversationQuery,
+  GetAllConversationsQuery,
+  DeleteAiDocumentMutation,
+  UpdateAiDocumentMutation,
+  UploadAiDocumentMutation,
+  UpdateAiSettingsMutation,
+  GetAiSettingsQuery,
+} from "./generated/apiHooks";
+
+/**
+ * Context passed to callbacks containing both request and response data
+ */
+export interface CallbackContext<TRequest, TResponse> {
+  /**
+   * The original request details
+   */
+  request: {
+    /**
+     * The full path of the request (e.g., "/ai-assistant?targetPath=/api")
+     */
+    path: string;
+    /**
+     * The HTTP method (POST, GET, etc.)
+     */
+    method: string;
+    /**
+     * The parsed request body
+     */
+    body: TRequest;
+  };
+  /**
+   * The parsed response body from the proxied request
+   */
+  response: TResponse;
+}
+
+/**
+ * REST endpoint request/response types
+ */
+
+export interface ChatRequest {
+  model?: "large" | "medium" | "small";
+  temperature?: number;
+  stream?: boolean;
+  maxTokens?: number;
+  messages: Array<{
+    role: "user" | "model" | "tool";
+    parts: Array<
+      | {
+          type: "text";
+          text: string;
+        }
+      | {
+          type: "toolCall";
+          toolName: string;
+          args: Record<string, unknown>;
+        }
+      | {
+          type: "toolResult";
+          toolName: string;
+          result: unknown;
+        }
+    >;
+    name?: string;
+  }>;
+}
+
+export interface ChatResponse {
+  role: "user" | "model" | "tool";
+  parts: Array<
+    | {
+        type: "text";
+        text: string;
+      }
+    | {
+        type: "toolCall";
+        toolName: string;
+        args: Record<string, unknown>;
+      }
+    | {
+        type: "toolResult";
+        toolName: string;
+        result: unknown;
+      }
+  >;
+}
+
+export interface StructuredResponseRequest {
+  model?: "large" | "medium" | "small";
+  prompt: string;
+  schema: unknown;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export type StructuredResponseResponse = unknown;
+
+export interface TTSRequest {
+  text: string;
+  voice?: string;
+}
+
+export interface TTSResponse {
+  synthesis: string;
+}
+
+export interface STTRequest {
+  audio: string;
+}
+
+export interface STTResponse {
+  transcription: Array<{
+    transcript: string;
+    confidence: number;
+  }>;
+}
+
+/**
+ * GraphQL request wrapper
+ */
+export interface GraphQLRequest<TVariables = unknown> {
+  operationName?: string;
+  query: string;
+  variables?: TVariables;
+}
+
+/**
+ * GraphQL response wrapper with potential errors
+ */
+export interface GraphQLResponse<TData = unknown> {
+  data?: TData;
+  errors?: Array<{
+    message: string;
+    extensions?: Record<string, unknown>;
+  }>;
+}
+
+/**
+ * Callbacks for REST endpoints
+ * Note: Keys are URL paths, not following camelCase convention intentionally
+ */
+export interface RestEndpointCallbacks {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  "/api/api-ai-assistant/v1/chat"?: (
+    context: CallbackContext<ChatRequest, ChatResponse>
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  "/api/api-ai-assistant/v1/structured-response"?: (
+    context: CallbackContext<
+      StructuredResponseRequest,
+      StructuredResponseResponse
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  "/api/api-ai-assistant/v1/tts"?: (
+    context: CallbackContext<TTSRequest, TTSResponse>
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  "/api/api-ai-assistant/v1/stt"?: (
+    context: CallbackContext<STTRequest, STTResponse>
+  ) => void | Promise<void>;
+}
+
+/**
+ * Callbacks for GraphQL operations
+ * Note: Keys match the GraphQL operation names (PascalCase), not the field names
+ */
+export interface GraphQLOperationCallbacks {
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  AppendMessageToConversation?: (
+    context: CallbackContext<
+      GraphQLRequest<{ input: AppendMessageInput }>,
+      GraphQLResponse<AppendMessageToConversationMutation>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  GetAConversation?: (
+    context: CallbackContext<
+      GraphQLRequest<{ input: ConversationInput }>,
+      GraphQLResponse<GetAConversationQuery>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  GetAllConversations?: (
+    context: CallbackContext<
+      GraphQLRequest<Record<string, never>>,
+      GraphQLResponse<GetAllConversationsQuery>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  CreateConversation?: (
+    context: CallbackContext<
+      GraphQLRequest<{ input: CreateConversationInput }>,
+      GraphQLResponse
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  DeleteConversation?: (
+    context: CallbackContext<
+      GraphQLRequest<{ input: DeleteConversationInput }>,
+      GraphQLResponse
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  UpdateConversationTitle?: (
+    context: CallbackContext<
+      GraphQLRequest<{ input: UpdateConversationTitleInput }>,
+      GraphQLResponse
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  DeleteAiDocument?: (
+    context: CallbackContext<
+      GraphQLRequest<unknown>,
+      GraphQLResponse<DeleteAiDocumentMutation>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  UpdateAiDocument?: (
+    context: CallbackContext<
+      GraphQLRequest<unknown>,
+      GraphQLResponse<UpdateAiDocumentMutation>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  UploadAiDocument?: (
+    context: CallbackContext<
+      GraphQLRequest<unknown>,
+      GraphQLResponse<UploadAiDocumentMutation>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  UpdateAiSettings?: (
+    context: CallbackContext<
+      GraphQLRequest<unknown>,
+      GraphQLResponse<UpdateAiSettingsMutation>
+    >
+  ) => void | Promise<void>;
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  GetAiSettings?: (
+    context: CallbackContext<
+      GraphQLRequest<Record<string, never>>,
+      GraphQLResponse<GetAiSettingsQuery>
+    >
+  ) => void | Promise<void>;
+}

package/build/constants.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * This file contains constants for the WorkTango Coach AI Assistant. It should
+ * contain no imports or dependencies: just constants and JSDoc types.
+ *
+ * We use it for sharing prompts and other data between systems in as light a way
+ * as possible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workTangoCoachGlobalSuggestedPrompts = exports.workTangoCoachSystemInstruction = void 0;
+exports.workTangoCoachSystemInstruction = `You are a 'Leadership Coach'. Your purpose is to empower People Leaders by providing guidance, resources, and tools to enhance their leadership capabilities. You will assist users in various aspects of leadership development, from problem-solving to goal setting and self-reflection. Sometimes you will be tasked with analyzing Survey Results. The Survey Results will inform the Coaching focus.
+
+Purpose and Goals:
+
+* **Guidance and Research:** Help users research and understand effective approaches to specific leadership challenges, issues, or topics.
+* **Self-Assessment Support:** Assist users in conducting self-assessments to identify their strengths, weaknesses, and areas for development as leaders.
+* **Goal Setting Facilitation:** Guide users through the process of setting clear, actionable, and measurable leadership goals.
+* **Reflective Questioning:** Engage users in reflective exercises using 'Powerful Questions' to encourage introspection and deeper understanding of their leadership journey.
+* **Knowledge Transfer:** Educate users on leadership theories, best practices, and effective strategies for leading teams and organizations.
+
+Behaviors and Rules:
+
+**Initial Engagement:**
+- If asked about something specific, you can skip the formal introduction, otherwise:
+- Greet the user warmly as their 'Leadership Coach' and express readiness to assist them in their growth as a Leader
+- List common requests you're designed to handle (research, self-assessment, goal setting, reflection, teaching).
+- Indicate that the session will be 5-10 mins
+- Ask the user to specify which of these areas they'd like to focus on first, or if they have a different leadership challenge in mind.
+
+**Interactive Support:**
+
+- For research requests, ask clarifying questions to understand the specific challenge or topic, then provide concise, actionable insights or resources.
+- For self-assessment, present frameworks or prompts, and encourage the user to share their thoughts, offering constructive feedback.
+- For goal setting, help the user define SMART (Specific, - Measurable, Achievable, Relevant, Time-bound) goals, breaking them down into manageable steps.
+- When using 'Powerful Questions', pose open-ended, thought-provoking questions that encourage deep reflection rather than simple 'yes/no' answers.
+- When teaching, break down complex concepts into understandable segments, providing examples and real-world applications.
+
+**Coaching Approach:**
+
+- Aim for a 5-10 minute coaching session
+- Maintain a supportive, encouraging, and non-judgmental demeanor.
+- Propose paths forward and look for input on the relevance of what is being suggested
+- Encourage active participation and critical thinking from the user.
+- Keep responses concise and clear, generally within 2-3 sentences per turn, allowing for a dynamic conversation flow.
+- Always end the conversation with a summary of the discussions and recommended actions for the People Leader
+
+Overall Tone:
+
+* **Empowering and Positive:** Foster a sense of capability and growth in the user.
+* **Knowledgeable and Trustworthy:** Convey expertise in leadership principles and practices.
+* **Patient and Understanding:** Recognize the complexities of leadership and support users through their challenges.
+* **Action-Oriented:** Encourage practical application of learned concepts.
+`;
+/**
+ * @typedef {Object} AiAssistantSuggestedPrompt
+ * @property {string} title - The title of the suggested prompt.
+ * @property {string} [fullPrompt] - The full prompt to be used. If not provided, the title will be used as the prompt.
+ */
+/**
+ * Globally-available suggested prompts used between platforms.
+ * @type {AiAssistantSuggestedPrompt[]}
+ */
+exports.workTangoCoachGlobalSuggestedPrompts = [
+    {
+        title: "Help me research how to approach a specific challenge, issue or topic",
+    },
+    { title: "Help me set effective goals for my team" },
+    { title: "Help me structure better 1-on-1s with my team" },
+    { title: "Help me reflect with powerful questions" },
+    { title: "Help me have a difficult conversation with a team member" },
+    { title: "Help me delegate more effectively" },
+    { title: "Help me with a self assessment" },
+    {
+        title: "How do I adapt my leadership approach to different personalities?",
+    },
+    { title: "How do I keep my team motivated during a crunch period?" },
+    { title: "How do I make space for strategic thinking amid daily fires?" },
+    { title: "How can I communicate a tough change to my team with empathy?" },
+];
+//# sourceMappingURL=constants.js.map

package/build/dist/express.d.ts

@@ -0,0 +1,2 @@
+declare const _exports: any;
+export = _exports;