@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/src/hooks/use-copilot-chat-suggestions.tsx

@@ -0,0 +1,124 @@
+/**
+ * <Callout type="warning">
+ *   useCopilotChatSuggestions is experimental. The interface is not final and
+ *   can change without notice.
+ * </Callout>
+ *
+ * `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.
+ *
+ * <br/>
+ * <img src="https://cdn.copilotkit.ai/docs/copilotkit/images/use-copilot-chat-suggestions/use-copilot-chat-suggestions.gif" width="500" />
+ *
+ * ## Usage
+ *
+ * ### Install Dependencies
+ *
+ * This component is part of the [@copilotkit/react-ui](https://npmjs.com/package/@copilotkit/react-ui) package.
+ *
+ * ```shell npm2yarn \"@copilotkit/react-ui"\
+ * npm install @copilotkit/react-core @copilotkit/react-ui
+ * ```
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * import { useCopilotChatSuggestions } from "@copilotkit/react-ui";
+ *
+ * export function MyComponent() {
+ *   const [employees, setEmployees] = useState([]);
+ *
+ *   useCopilotChatSuggestions({
+ *     instructions: `The following employees are on duty: ${JSON.stringify(employees)}`,
+ *   });
+ * }
+ * ```
+ *
+ * ### Dependency Management
+ *
+ * ```tsx
+ * import { useCopilotChatSuggestions } from "@copilotkit/react-ui";
+ *
+ * export function MyComponent() {
+ *   useCopilotChatSuggestions(
+ *     {
+ *       instructions: "Suggest the most relevant next actions.",
+ *     },
+ *     [appState],
+ *   );
+ * }
+ * ```
+ *
+ * In the example above, the suggestions are generated based on the given instructions.
+ * The hook monitors `appState`, and updates suggestions accordingly whenever it changes.
+ *
+ * ### Behavior and Lifecycle
+ *
+ * The hook registers the configuration with the chat context upon component mount and
+ * removes it on unmount, ensuring a clean and efficient lifecycle management.
+ */
+import {
+  useConfigureSuggestions,
+  useCopilotChatConfiguration,
+  useCopilotKit,
+  useSuggestions,
+} from "@copilotkitnext/react";
+import { useEffect } from "react";
+import { StaticSuggestionsConfig, Suggestion } from "@copilotkitnext/core";
+
+type StaticSuggestionInput = Omit<Suggestion, "isLoading"> & Partial<Pick<Suggestion, "isLoading">>;
+
+type StaticSuggestionsConfigInput = Omit<StaticSuggestionsConfig, "suggestions"> & {
+  suggestions: StaticSuggestionInput[];
+};
+
+type DynamicSuggestionsConfigInput = {
+  /**
+   * A prompt or instructions for the GPT to generate suggestions.
+   */
+  instructions: string;
+  /**
+   * The minimum number of suggestions to generate. Defaults to `1`.
+   * @default 1
+   */
+  minSuggestions?: number;
+  /**
+   * The maximum number of suggestions to generate. Defaults to `3`.
+   * @default 1
+   */
+  maxSuggestions?: number;
+
+  /**
+   * Whether the suggestions are available. Defaults to `enabled`.
+   * @default enabled
+   */
+  available?: "enabled" | "disabled" | "always" | "before-first-message" | "after-first-message";
+
+  /**
+   * An optional class name to apply to the suggestions.
+   */
+  className?: string;
+};
+
+export type UseCopilotChatSuggestionsConfiguration =
+  | DynamicSuggestionsConfigInput
+  | StaticSuggestionsConfigInput;
+
+export function useCopilotChatSuggestions(
+  config: UseCopilotChatSuggestionsConfiguration,
+  dependencies: any[] = [],
+) {
+  const existingConfig = useCopilotChatConfiguration();
+  const resolvedAgentId = existingConfig?.agentId ?? "default";
+
+  const available =
+    (config.available === "enabled" ? "always" : config.available) ?? "before-first-message";
+
+  const finalSuggestionConfig = {
+    ...config,
+    available,
+    consumerAgentId: resolvedAgentId, // Use chatConfig.agentId here
+  };
+  useConfigureSuggestions(finalSuggestionConfig, dependencies);
+}

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

@@ -0,0 +1,130 @@
+/**
+ * `useCopilotChat` is a lightweight React hook for headless chat interactions.
+ * Perfect for controlling the prebuilt chat components programmatically.
+ *
+ * **Open Source Friendly** - Works without requiring a free public license key.
+ *
+ * <Callout title="Looking for fully headless UI?">
+ * Get started with [useCopilotChatHeadless_c](https://docs.copilotkit.ai/reference/hooks/useCopilotChatHeadless_c).
+ * </Callout>
+ *
+ * ## Use Cases
+ *
+ * - **Programmatic Messaging**: Send messages without displaying chat UI
+ * - **Programmatic control**: Control prebuilt component programmatically
+ * - **Background Operations**: Trigger AI interactions in the background
+ * - **Fire-and-Forget**: Send messages without needing to read responses
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { TextMessage, MessageRole } from "@copilotkit/runtime-client-gql";
+ *
+ * const { appendMessage } = useCopilotChat();
+ *
+ * // Example usage without naming conflicts
+ * const handleSendMessage = async (content: string) => {
+ *   await appendMessage(
+ *     new TextMessage({
+ *       role: MessageRole.User,
+ *       content,
+ *     })
+ *   );
+ * };
+ * ```
+ *
+ * ## Return Values
+ * The following properties are returned from the hook:
+ *
+ * <PropertyReference name="visibleMessages" type="DeprecatedGqlMessage[]" deprecated>
+ * Array of messages in old non-AG-UI format, use for compatibility only
+ * </PropertyReference>
+ *
+ * <PropertyReference name="appendMessage" type="(message: DeprecatedGqlMessage, options?) => Promise<void>" deprecated>
+ * Append message using old format, use `sendMessage` instead
+ * </PropertyReference>
+ *
+ * <PropertyReference name="reloadMessages" type="(messageId: string) => Promise<void>">
+ * Regenerate the response for a specific message by ID
+ * </PropertyReference>
+ *
+ * <PropertyReference name="stopGeneration" type="() => void">
+ * Stop the current message generation process
+ * </PropertyReference>
+ *
+ * <PropertyReference name="reset" type="() => void">
+ * Clear all messages and reset chat state completely
+ * </PropertyReference>
+ *
+ * <PropertyReference name="isLoading" type="boolean">
+ * Whether the chat is currently generating a response
+ * </PropertyReference>
+ *
+ * <PropertyReference name="runChatCompletion" type="() => Promise<Message[]>">
+ * Manually trigger chat completion for advanced usage
+ * </PropertyReference>
+ *
+ * <PropertyReference name="mcpServers" type="MCPServerConfig[]">
+ * Array of Model Context Protocol server configurations
+ * </PropertyReference>
+ *
+ * <PropertyReference name="setMcpServers" type="(servers: MCPServerConfig[]) => void">
+ * Update MCP server configurations for enhanced context
+ * </PropertyReference>
+ */
+
+import {
+  UseCopilotChatOptions,
+  useCopilotChatInternal,
+  UseCopilotChatReturn as UseCopilotChatReturnInternal,
+} from "./use-copilot-chat_internal";
+
+// Create a type that excludes message-related properties from the internal type
+export type UseCopilotChatReturn = Omit<
+  UseCopilotChatReturnInternal,
+  | "messages"
+  | "sendMessage"
+  | "suggestions"
+  | "setSuggestions"
+  | "generateSuggestions"
+  | "isLoadingSuggestions"
+  | "resetSuggestions"
+  | "interrupt"
+  | "setMessages"
+  | "deleteMessage"
+>;
+
+/**
+ * A lightweight React hook for headless chat interactions.
+ * Perfect for programmatic messaging, background operations, and custom UI implementations.
+ *
+ * **Open Source Friendly** - Works without requiring a `publicApiKey`.
+ */
+// TODO: Do we need this? If so, does it work properly? test.
+export function useCopilotChat(options: UseCopilotChatOptions = {}): UseCopilotChatReturn {
+  const {
+    visibleMessages,
+    appendMessage,
+    reloadMessages,
+    stopGeneration,
+    reset,
+    isLoading,
+    isAvailable,
+    runChatCompletion,
+    mcpServers,
+    setMcpServers,
+  } = useCopilotChatInternal(options);
+
+  return {
+    visibleMessages,
+    appendMessage,
+    reloadMessages,
+    stopGeneration,
+    reset,
+    isLoading,
+    isAvailable,
+    runChatCompletion,
+    mcpServers,
+    setMcpServers,
+  };
+}