@copilotkit/react-core 0.0.0-feat-dynamic-copilotcloud-qa-20250117190454

package/src/hooks/use-copilot-readable.ts

@@ -0,0 +1,123 @@
+/**
+ * `useCopilotReadable` is a React hook that provides app-state and other information
+ * to the Copilot. Optionally, the hook can also handle hierarchical state within your
+ * application, passing these parent-child relationships to the Copilot.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * In its most basic usage, useCopilotReadable accepts a single string argument
+ * representing any piece of app state, making it available for the Copilot to use
+ * as context when responding to user input.
+ *
+ * ```tsx
+ * import { useCopilotReadable } from "@copilotkit/react-core";
+ *
+ * export function MyComponent() {
+ *   const [employees, setEmployees] = useState([]);
+ *
+ *   useCopilotReadable({
+ *     description: "The list of employees",
+ *     value: employees,
+ *   });
+ * }
+ * ```
+ *
+ * ### Nested Components
+ *
+ * Optionally, you can maintain the hierarchical structure of information by passing
+ * `parentId`. This allows you to use `useCopilotReadable` in nested components:
+ *
+ * ```tsx /employeeContextId/1 {17,23}
+ * import { useCopilotReadable } from "@copilotkit/react-core";
+ *
+ * function Employee(props: EmployeeProps) {
+ *   const { employeeName, workProfile, metadata } = props;
+ *
+ *   // propagate any information to copilot
+ *   const employeeContextId = useCopilotReadable({
+ *     description: "Employee name",
+ *     value: employeeName
+ *   });
+ *
+ *   // Pass a parentID to maintain a hierarchical structure.
+ *   // Especially useful with child React components, list elements, etc.
+ *   useCopilotReadable({
+ *     description: "Work profile",
+ *     value: workProfile.description(),
+ *     parentId: employeeContextId
+ *   });
+ *
+ *   useCopilotReadable({
+ *     description: "Employee metadata",
+ *     value: metadata.description(),
+ *     parentId: employeeContextId
+ *   });
+ *
+ *   return (
+ *     // Render as usual...
+ *   );
+ * }
+ * ```
+ */
+import { useEffect, useRef } from "react";
+import { useCopilotContext } from "../context/copilot-context";
+
+/**
+ * Options for the useCopilotReadable hook.
+ */
+export interface UseCopilotReadableOptions {
+  /**
+   * The description of the information to be added to the Copilot context.
+   */
+  description: string;
+  /**
+   * The value to be added to the Copilot context. Object values are automatically stringified.
+   */
+  value: any;
+  /**
+   * The ID of the parent context, if any.
+   */
+  parentId?: string;
+  /**
+   * An array of categories to control which context are visible where. Particularly useful
+   * with CopilotTextarea (see `useMakeAutosuggestionFunction`)
+   */
+  categories?: string[];
+
+  /**
+   * A custom conversion function to use to serialize the value to a string. If not provided, the value
+   * will be serialized using `JSON.stringify`.
+   */
+  convert?: (description: string, value: any) => string;
+}
+
+function convertToJSON(description: string, value: any): string {
+  return `${description}: ${typeof value === "string" ? value : JSON.stringify(value)}`;
+}
+
+/**
+ * Adds the given information to the Copilot context to make it readable by Copilot.
+ */
+export function useCopilotReadable(
+  { description, value, parentId, categories, convert }: UseCopilotReadableOptions,
+  dependencies?: any[],
+): string | undefined {
+  const { addContext, removeContext } = useCopilotContext();
+  const idRef = useRef<string>();
+  convert = convert || convertToJSON;
+
+  const information = convert(description, value);
+
+  useEffect(() => {
+    const id = addContext(information, parentId, categories);
+    idRef.current = id;
+
+    return () => {
+      removeContext(id);
+    };
+  }, [information, parentId, addContext, removeContext, ...(dependencies || [])]);
+
+  return idRef.current;
+}

package/src/hooks/use-copilot-runtime-client.ts

@@ -0,0 +1,28 @@
+import {
+  CopilotRuntimeClient,
+  CopilotRuntimeClientOptions,
+  GraphQLError,
+} from "@copilotkit/runtime-client-gql";
+import { useToast } from "../components/toast/toast-provider";
+import { useMemo } from "react";
+import { useErrorToast } from "../components/error-boundary/error-utils";
+
+export const useCopilotRuntimeClient = (options: CopilotRuntimeClientOptions) => {
+  const { addGraphQLErrorsToast } = useToast();
+  const addErrorToast = useErrorToast();
+
+  const runtimeClient = useMemo(() => {
+    return new CopilotRuntimeClient({
+      ...options,
+      handleGQLErrors: (error) => {
+        if ((error as any).graphQLErrors.length) {
+          addGraphQLErrorsToast((error as any).graphQLErrors as GraphQLError[]);
+        } else {
+          addErrorToast([error]);
+        }
+      },
+    });
+  }, [options, addGraphQLErrorsToast]);
+
+  return runtimeClient;
+};

package/src/hooks/use-flat-category-store.ts

@@ -0,0 +1,104 @@
+import { useCallback, useReducer } from "react";
+import { randomId } from "@copilotkit/shared";
+
+export type FlatCategoryStoreId = string;
+
+export interface UseFlatCategoryStoreReturn<T> {
+  addElement: (value: T, categories: string[]) => FlatCategoryStoreId;
+  removeElement: (id: FlatCategoryStoreId) => void;
+  allElements: (categories: string[]) => T[];
+}
+
+interface FlatCategoryStoreElement<T> {
+  id: FlatCategoryStoreId;
+  value: T;
+  categories: Set<string>;
+}
+
+const useFlatCategoryStore = <T>(): UseFlatCategoryStoreReturn<T> => {
+  const [elements, dispatch] = useReducer<
+    React.Reducer<Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>>, Action<T>>
+  >(flatCategoryStoreReducer, new Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>>());
+
+  const addElement = useCallback((value: T, categories: string[]): FlatCategoryStoreId => {
+    const newId = randomId();
+    dispatch({
+      type: "ADD_ELEMENT",
+      value,
+      id: newId,
+      categories,
+    });
+    return newId;
+  }, []);
+
+  const removeElement = useCallback((id: FlatCategoryStoreId): void => {
+    dispatch({ type: "REMOVE_ELEMENT", id });
+  }, []);
+
+  const allElements = useCallback(
+    (categories: string[]): T[] => {
+      const categoriesSet = new Set(categories);
+      const result: T[] = [];
+      elements.forEach((element) => {
+        if (setsHaveIntersection(categoriesSet, element.categories)) {
+          result.push(element.value);
+        }
+      });
+      return result;
+    },
+    [elements],
+  );
+
+  return { addElement, removeElement, allElements };
+};
+
+export default useFlatCategoryStore;
+
+// Action types
+type Action<T> =
+  | {
+      type: "ADD_ELEMENT";
+      value: T;
+      id: FlatCategoryStoreId;
+      categories: string[];
+    }
+  | { type: "REMOVE_ELEMENT"; id: FlatCategoryStoreId };
+
+// Reducer
+function flatCategoryStoreReducer<T>(
+  state: Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>>,
+  action: Action<T>,
+): Map<FlatCategoryStoreId, FlatCategoryStoreElement<T>> {
+  switch (action.type) {
+    case "ADD_ELEMENT": {
+      const { value, id, categories } = action;
+      const newElement: FlatCategoryStoreElement<T> = {
+        id,
+        value,
+        categories: new Set(categories),
+      };
+      const newState = new Map(state);
+      newState.set(id, newElement);
+      return newState;
+    }
+    case "REMOVE_ELEMENT": {
+      const newState = new Map(state);
+      newState.delete(action.id);
+      return newState;
+    }
+    default:
+      return state;
+  }
+}
+
+function setsHaveIntersection<T>(setA: Set<T>, setB: Set<T>): boolean {
+  const [smallerSet, largerSet] = setA.size <= setB.size ? [setA, setB] : [setB, setA];
+
+  for (let item of smallerSet) {
+    if (largerSet.has(item)) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/hooks/use-make-copilot-document-readable.ts

@@ -0,0 +1,30 @@
+import { useEffect, useRef } from "react";
+import { useCopilotContext } from "../context/copilot-context";
+import { DocumentPointer } from "../types";
+
+/**
+ * Makes a document readable by Copilot.
+ * @param document The document to make readable.
+ * @param categories The categories to associate with the document.
+ * @param dependencies The dependencies to use for the effect.
+ * @returns The id of the document.
+ */
+export function useMakeCopilotDocumentReadable(
+  document: DocumentPointer,
+  categories?: string[],
+  dependencies: any[] = [],
+): string | undefined {
+  const { addDocumentContext, removeDocumentContext } = useCopilotContext();
+  const idRef = useRef<string>();
+
+  useEffect(() => {
+    const id = addDocumentContext(document, categories);
+    idRef.current = id;
+
+    return () => {
+      removeDocumentContext(id);
+    };
+  }, [addDocumentContext, removeDocumentContext, ...dependencies]);
+
+  return idRef.current;
+}

package/src/hooks/use-tree.ts

@@ -0,0 +1,202 @@
+import { randomId } from "@copilotkit/shared";
+import { useCallback, useReducer } from "react";
+
+export type TreeNodeId = string;
+
+export interface TreeNode {
+  id: TreeNodeId;
+  value: string;
+  children: TreeNode[];
+  parentId?: TreeNodeId;
+  categories: Set<string>;
+}
+
+export type Tree = TreeNode[];
+
+export interface UseTreeReturn {
+  tree: Tree;
+  addElement: (value: string, categories: string[], parentId?: TreeNodeId) => TreeNodeId;
+  printTree: (categories: string[]) => string;
+  removeElement: (id: TreeNodeId) => void;
+}
+
+const findNode = (nodes: Tree, id: TreeNodeId): TreeNode | undefined => {
+  for (const node of nodes) {
+    if (node.id === id) {
+      return node;
+    }
+    const result = findNode(node.children, id);
+    if (result) {
+      return result;
+    }
+  }
+  return undefined;
+};
+
+const removeNode = (nodes: Tree, id: TreeNodeId): Tree => {
+  return nodes.reduce((result: Tree, node) => {
+    if (node.id !== id) {
+      const newNode = { ...node, children: removeNode(node.children, id) };
+      result.push(newNode);
+    }
+    return result;
+  }, []);
+};
+
+const addNode = (nodes: Tree, newNode: TreeNode, parentId?: TreeNodeId): Tree => {
+  if (!parentId) {
+    return [...nodes, newNode];
+  }
+  return nodes.map((node) => {
+    if (node.id === parentId) {
+      return { ...node, children: [...node.children, newNode] };
+    } else if (node.children.length) {
+      return { ...node, children: addNode(node.children, newNode, parentId) };
+    }
+    return node;
+  });
+};
+
+const treeIndentationRepresentation = (index: number, indentLevel: number): string => {
+  if (indentLevel === 0) {
+    return (index + 1).toString();
+  } else if (indentLevel === 1) {
+    return String.fromCharCode(65 + index); // 65 is the ASCII value for 'A'
+  } else if (indentLevel === 2) {
+    return String.fromCharCode(97 + index); // 97 is the ASCII value for 'a'
+  } else {
+    return "-";
+  }
+};
+
+const printNode = (node: TreeNode, prefix = "", indentLevel = 0): string => {
+  const indent = " ".repeat(3).repeat(indentLevel);
+
+  const prefixPlusIndentLength = prefix.length + indent.length;
+  const subsequentLinesPrefix = " ".repeat(prefixPlusIndentLength);
+
+  const valueLines = node.value.split("\n");
+
+  const outputFirstLine = `${indent}${prefix}${valueLines[0]}`;
+  const outputSubsequentLines = valueLines
+    .slice(1)
+    .map((line) => `${subsequentLinesPrefix}${line}`)
+    .join("\n");
+
+  let output = `${outputFirstLine}\n`;
+  if (outputSubsequentLines) {
+    output += `${outputSubsequentLines}\n`;
+  }
+
+  const childPrePrefix = " ".repeat(prefix.length);
+
+  node.children.forEach(
+    (child, index) =>
+      (output += printNode(
+        child,
+        `${childPrePrefix}${treeIndentationRepresentation(index, indentLevel + 1)}. `,
+        indentLevel + 1,
+      )),
+  );
+  return output;
+};
+
+// Action types
+type Action =
+  | {
+      type: "ADD_NODE";
+      value: string;
+      parentId?: string;
+      id: string;
+      categories: string[];
+    }
+  | { type: "REMOVE_NODE"; id: string };
+
+// Reducer function
+function treeReducer(state: Tree, action: Action): Tree {
+  switch (action.type) {
+    case "ADD_NODE": {
+      const { value, parentId, id: newNodeId } = action;
+      const newNode: TreeNode = {
+        id: newNodeId,
+        value,
+        children: [],
+        categories: new Set(action.categories),
+      };
+
+      try {
+        return addNode(state, newNode, parentId);
+      } catch (error) {
+        console.error(`Error while adding node with id ${newNodeId}: ${error}`);
+        return state;
+      }
+    }
+    case "REMOVE_NODE":
+      return removeNode(state, action.id);
+    default:
+      return state;
+  }
+}
+
+// useTree hook
+const useTree = (): UseTreeReturn => {
+  const [tree, dispatch] = useReducer(treeReducer, []);
+
+  const addElement = useCallback(
+    (value: string, categories: string[], parentId?: string): TreeNodeId => {
+      const newNodeId = randomId(); // Generate new ID outside of dispatch
+      dispatch({
+        type: "ADD_NODE",
+        value,
+        parentId,
+        id: newNodeId,
+        categories: categories,
+      });
+      return newNodeId; // Return the new ID
+    },
+    [],
+  );
+
+  const removeElement = useCallback((id: TreeNodeId): void => {
+    dispatch({ type: "REMOVE_NODE", id });
+  }, []);
+
+  const printTree = useCallback(
+    (categories: string[]): string => {
+      const categoriesSet = new Set(categories);
+
+      let output = "";
+      tree.forEach((node, index) => {
+        // if the node does not have any of the desired categories, continue to the next node
+        if (!setsHaveIntersection(categoriesSet, node.categories)) {
+          return;
+        }
+
+        // add a new line before each node except the first one
+        if (index !== 0) {
+          output += "\n";
+        }
+
+        output += printNode(node, `${treeIndentationRepresentation(index, 0)}. `);
+      });
+      return output;
+    },
+    [tree],
+  );
+
+  return { tree, addElement, printTree, removeElement };
+};
+
+export default useTree;
+
+function setsHaveIntersection<T>(setA: Set<T>, setB: Set<T>): boolean {
+  const [smallerSet, largerSet] = setA.size <= setB.size ? [setA, setB] : [setB, setA];
+
+  for (let item of smallerSet) {
+    if (largerSet.has(item)) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/index.tsx

@@ -0,0 +1,7 @@
+"use client";
+export * from "./components";
+export * from "./context";
+export * from "./hooks";
+export * from "./types";
+export * from "./lib";
+export * from "./utils";

package/src/lib/copilot-task.ts

@@ -0,0 +1,201 @@
+/**
+ * This class is used to execute one-off tasks, for example on button press. It can use the context available via [useCopilotReadable](/reference/hooks/useCopilotReadable) and the actions provided by [useCopilotAction](/reference/hooks/useCopilotAction), or you can provide your own context and actions.
+ *
+ * ## Example
+ * In the simplest case, use CopilotTask in the context of your app by giving it instructions on what to do.
+ *
+ * ```tsx
+ * import { CopilotTask, useCopilotContext } from "@copilotkit/react-core";
+ *
+ * export function MyComponent() {
+ *   const context = useCopilotContext();
+ *
+ *   const task = new CopilotTask({
+ *     instructions: "Set a random message",
+ *     actions: [
+ *       {
+ *         name: "setMessage",
+ *       description: "Set the message.",
+ *       argumentAnnotations: [
+ *         {
+ *           name: "message",
+ *           type: "string",
+ *           description:
+ *             "A message to display.",
+ *           required: true,
+ *         },
+ *       ],
+ *      }
+ *     ]
+ *   });
+ *
+ *   const executeTask = async () => {
+ *     await task.run(context, action);
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={executeTask}>
+ *         Execute task
+ *       </button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * Have a look at the [Presentation Example App](https://github.com/CopilotKit/CopilotKit/blob/main/CopilotKit/examples/next-openai/src/app/presentation/page.tsx) for a more complete example.
+ */
+
+import {
+  ActionExecutionMessage,
+  CopilotRuntimeClient,
+  Message,
+  Role,
+  TextMessage,
+  convertGqlOutputToMessages,
+  convertMessagesToGqlInput,
+  filterAgentStateMessages,
+  CopilotRequestType,
+  ForwardedParametersInput,
+} from "@copilotkit/runtime-client-gql";
+import { FrontendAction, processActionsForRuntimeRequest } from "../types/frontend-action";
+import { CopilotContextParams } from "../context";
+import { defaultCopilotContextCategories } from "../components";
+
+export interface CopilotTaskConfig {
+  /**
+   * The instructions to be given to the assistant.
+   */
+  instructions: string;
+  /**
+   * An array of action definitions that can be called.
+   */
+  actions?: FrontendAction<any>[];
+  /**
+   * Whether to include the copilot readable context in the task.
+   */
+  includeCopilotReadable?: boolean;
+
+  /**
+   * Whether to include actions defined via useCopilotAction in the task.
+   */
+  includeCopilotActions?: boolean;
+
+  /**
+   * The forwarded parameters to use for the task.
+   */
+  forwardedParameters?: ForwardedParametersInput;
+}
+
+export class CopilotTask<T = any> {
+  private instructions: string;
+  private actions: FrontendAction<any>[];
+  private includeCopilotReadable: boolean;
+  private includeCopilotActions: boolean;
+  private forwardedParameters?: ForwardedParametersInput;
+  constructor(config: CopilotTaskConfig) {
+    this.instructions = config.instructions;
+    this.actions = config.actions || [];
+    this.includeCopilotReadable = config.includeCopilotReadable !== false;
+    this.includeCopilotActions = config.includeCopilotActions !== false;
+    this.forwardedParameters = config.forwardedParameters;
+  }
+
+  /**
+   * Run the task.
+   * @param context The CopilotContext to use for the task. Use `useCopilotContext` to obtain the current context.
+   * @param data The data to use for the task.
+   */
+  async run(context: CopilotContextParams, data?: T): Promise<void> {
+    const actions = this.includeCopilotActions ? Object.assign({}, context.actions) : {};
+
+    // merge functions into entry points
+    for (const fn of this.actions) {
+      actions[fn.name] = fn;
+    }
+
+    let contextString = "";
+
+    if (data) {
+      contextString = (typeof data === "string" ? data : JSON.stringify(data)) + "\n\n";
+    }
+
+    if (this.includeCopilotReadable) {
+      contextString += context.getContextString([], defaultCopilotContextCategories);
+    }
+
+    const systemMessage = new TextMessage({
+      content: taskSystemMessage(contextString, this.instructions),
+      role: Role.System,
+    });
+
+    const messages: Message[] = [systemMessage];
+
+    const runtimeClient = new CopilotRuntimeClient({
+      url: context.copilotApiConfig.chatApiEndpoint,
+      publicApiKey: context.copilotApiConfig.publicApiKey,
+      headers: context.copilotApiConfig.headers,
+      credentials: context.copilotApiConfig.credentials,
+    });
+
+    const response = await runtimeClient
+      .generateCopilotResponse({
+        data: {
+          frontend: {
+            actions: processActionsForRuntimeRequest(Object.values(actions)),
+            url: window.location.href,
+          },
+          messages: convertMessagesToGqlInput(filterAgentStateMessages(messages)),
+          metadata: {
+            requestType: CopilotRequestType.Task,
+          },
+          forwardedParameters: {
+            // if forwardedParameters is provided, use it
+            ...(this.forwardedParameters ?? {}),
+            toolChoice: "required",
+          },
+        },
+        properties: context.copilotApiConfig.properties,
+      })
+      .toPromise();
+
+    const functionCallHandler = context.getFunctionCallHandler(actions);
+    const functionCalls = convertGqlOutputToMessages(
+      response.data?.generateCopilotResponse?.messages || [],
+    ).filter((m): m is ActionExecutionMessage => m.isActionExecutionMessage());
+
+    for (const functionCall of functionCalls) {
+      await functionCallHandler({
+        messages,
+        name: functionCall.name,
+        args: functionCall.arguments,
+      });
+    }
+  }
+}
+
+function taskSystemMessage(contextString: string, instructions: string): string {
+  return `
+Please act as an efficient, competent, conscientious, and industrious professional assistant.
+
+Help the user achieve their goals, and you do so in a way that is as efficient as possible, without unnecessary fluff, but also without sacrificing professionalism.
+Always be polite and respectful, and prefer brevity over verbosity.
+
+The user has provided you with the following context:
+\`\`\`
+${contextString}
+\`\`\`
+
+They have also provided you with functions you can call to initiate actions on their behalf.
+
+Please assist them as best you can.
+
+This is not a conversation, so please do not ask questions. Just call a function without saying anything else.
+
+The user has given you the following task to complete:
+
+\`\`\`
+${instructions}
+\`\`\`
+`;
+}

package/src/lib/index.ts

@@ -0,0 +1 @@
+export * from "./copilot-task";