@automattic/jetpack-ai-client 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.9] - 2023-09-25
+### Added
+- Export GuidelineMessage for use in other blocks. [#33180]
+
+## [0.1.8] - 2023-09-19
+### Added
+- AI Client: Add support for the jetpack-ai role on the prompt messages. [#33052]
+- AI Client: add `model` param to request helpers [#33083]
+- AI Client: Emit specific error for large context error on SuggestionsEventSource [#33157]
+- AI Client: Introduce blockListBlockWithAiDataProvider() function [#33025]
+
+### Changed
+- AI Client: Move showGuideLine to AIControl component props [#33084]
+
+### Fixed
+- AI Client: check media record ref of the useMediaRecording() hook before to remove the listeners [#33013]
+
 ## [0.1.7] - 2023-09-11
 ### Added
 - AI Client: add and expose reset() from useAiSuggestions() hook [#32886]
@@ -115,6 +132,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31659]
 - Updated package dependencies. [#31785]
 
+[0.1.9]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.8...v0.1.9
+[0.1.8]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.4...v0.1.5

package/package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "@automattic/jetpack-ai-client",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"description": "A JS client for consuming Jetpack AI services",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/ai-client/#readme",
 	"bugs": {
@@ -33,8 +33,8 @@
 	},
 	"dependencies": {
 		"@automattic/jetpack-base-styles": "^0.6.9",
-		"@automattic/jetpack-connection": "^0.29.9",
-		"@automattic/jetpack-shared-extension-utils": "^0.11.4",
+		"@automattic/jetpack-connection": "^0.30.0",
+		"@automattic/jetpack-shared-extension-utils": "^0.12.0",
 		"@microsoft/fetch-event-source": "2.0.1",
 		"@wordpress/api-fetch": "6.38.0",
 		"@wordpress/block-editor": "12.9.0",

package/src/ask-question/Readme.md

@@ -22,6 +22,7 @@ function askQuestion(
     - **postId** (**number**, optional): ID of the post where the question is asked.
     - **fromCache** (**boolean**, optional): If set to true, the answer will be fetched from the cache. Default value is false.
     - **feature** (**string**, optional): Allows to use a specific AI assistant feature.
+    - **model**( **AiModelTypeProp** optional): Allows to use a specific AI model.
 
 ## Returns
 

package/src/ask-question/index.ts

@@ -6,7 +6,7 @@ import SuggestionsEventSource from '../suggestions-event-source';
 /*
  * Types & constants
  */
-import type { PromptProp } from '../types';
+import type { AiModelTypeProp, PromptProp } from '../types';
 
 export type AskQuestionOptionsArgProps = {
 	/*
@@ -24,6 +24,11 @@ export type AskQuestionOptionsArgProps = {
 	 */
 	feature?: 'ai-assistant-experimental' | string | undefined;
 
+	/*
+	 * Allows to use a specific AI model.
+	 */
+	model?: AiModelTypeProp;
+
 	/*
 	 * Allows the use of function calling. Default value is undefined.
 	 */
@@ -57,12 +62,18 @@ const debug = debugFactory( 'jetpack-ai-client:ask-question' );
  */
 export default async function askQuestion(
 	question: PromptProp,
-	{ postId = null, fromCache = false, feature, functions }: AskQuestionOptionsArgProps = {}
+	{ postId = null, fromCache = false, feature, functions, model }: AskQuestionOptionsArgProps = {}
 ): Promise< SuggestionsEventSource > {
-	debug( 'Asking question: %o. options: %o', question, { postId, fromCache, feature, functions } );
+	debug( 'Asking question: %o. options: %o', question, {
+		postId,
+		fromCache,
+		feature,
+		functions,
+		model,
+	} );
 
 	return new SuggestionsEventSource( {
 		question,
-		options: { postId, feature, fromCache, functions },
+		options: { postId, feature, fromCache, functions, model },
 	} );
 }

package/src/components/ai-control/index.tsx

@@ -36,6 +36,7 @@ const noop = () => {};
  * @param {boolean} props.isTransparent    - Whether the component has low opacity
  * @param {string} props.state             - The request state
  * @param {boolean} props.showClearButton  - Whether to show the clear button when the input has a value
+ * @param {boolean} props.showGuideLine    - WHether to show the guideline message
  * @param {Function} props.onChange        - Input change handler
  * @param {Function} props.onSend          - Request send handler
  * @param {Function} props.onStop          - Request stop handler
@@ -54,6 +55,7 @@ export function AIControl(
 		isTransparent = false,
 		state = 'init',
 		showClearButton = true,
+		showGuideLine = false,
 		onChange = noop,
 		onSend = noop,
 		onStop = noop,
@@ -68,6 +70,7 @@ export function AIControl(
 		isTransparent?: boolean;
 		state?: RequestingStateProp;
 		showClearButton?: boolean;
+		showGuideLine?: boolean;
 		onChange?: ( newValue: string ) => void;
 		onSend?: ( currentValue: string ) => void;
 		onStop?: () => void;
@@ -77,7 +80,6 @@ export function AIControl(
 ) {
 	const promptUserInputRef = useRef( null );
 	const loading = state === 'requesting' || state === 'suggesting';
-	const showGuideLine = ! ( loading || disabled || value?.length || isTransparent );
 
 	// Pass the ref to forwardRef.
 	useImperativeHandle( ref, () => promptUserInputRef.current );

package/src/components/index.ts

@@ -1,3 +1,4 @@
 export { default as AIControl } from './ai-control';
 export { default as AiStatusIndicator } from './ai-status-indicator';
 export { default as AudioDurationDisplay } from './audio-duration-display';
+export { GuidelineMessage } from './ai-control/message';

package/src/data-flow/Readme.md

@@ -33,6 +33,7 @@ export default withAiAssistantData( MyComponent );
 
 * [AI Data Context](#ai-assistant-content)
 * [withAiDataProvider HOC](#with-ai-data-provider)
+* [blockListBlockWithAiDataProvider](#block-list-block-with-ai-data-provider)
 * [useAiContext Hook](#use-ai-context)
 
 <h2 id="ai-assistant-content">Ai Data Context</h2>
@@ -113,3 +114,39 @@ Optional options object:
 These callbacks will be invoked with the detail of the corresponding event emitted by SuggestionsEventSource.
 
 When called, the hook returns the Ai Data Context.
+
+
+<h2 id="block-list-block-with-ai-data-provider">blockListBlockWithAiDataProvider Function</h2>
+
+The `blockListBlockWithAiDataProvider` function returns a Higher Order Component (HOC) that wraps and provides the AI Assistant Data context to a specified set of blocks. Primarily designed for use with the `editor.BlockListBlock` filter in the WordPress Block Editor, it conditionally applies the data provider only to block types specified in the function options.
+
+### Usage
+
+To use the `blockListBlockWithAiDataProvider`, you'll need to specify which blocks should have access to the AI Assistant Data context:
+
+```jsx
+import { blockListBlockWithAiDataProvider } from '@automattic/jetpack-ai-client';
+
+// Example usage with WordPress filters
+const enhancedBlockListBlock = blockListBlockWithAiDataProvider( {
+  blocks: [ 'core/paragraph', 'core/heading' ]
+} );
+
+wp.hooks.addFilter( 'editor.BlockListBlock', 'my-plugin/with-ai-data', enhancedBlockListBlock );
+```
+
+### Parameters
+
+The function accepts an optional options object:
+
+#### `options.blocks`
+- Type: `string[]`
+- Default: `['']`
+
+An array of block names (e.g., `[ 'core/paragraph', 'core/image' ]`) to which the data provider should be applied. Only the blocks specified in this array can access the AI Assistant Data context.
+
+### Returned Wrapped Component
+
+When a block type matches one of the specified names in `options.blocks`, the returned component will be wrapped with the AI Assistant Data context, providing all the available data and functionalities. The original component will be returned without any modifications for other block types.
+
+_Before using this function, ensure the AI Assistant Data is available in the higher component hierarchy. The [Ai Data Context](#ai-assistant-content) should typically wrap the top-level component or application._

package/src/data-flow/index.ts

@@ -1,3 +1,6 @@
 export { AiDataContext, AiDataContextProvider } from './context';
-export { default as withAiDataProvider } from './with-ai-assistant-data';
+export {
+	default as withAiDataProvider,
+	blockListBlockWithAiDataProvider,
+} from './with-ai-assistant-data';
 export { default as useAiContext } from './use-ai-context';

package/src/data-flow/with-ai-assistant-data.tsx

@@ -59,3 +59,82 @@ const withAiDataProvider = createHigherOrderComponent( ( WrappedComponent: React
 }, 'withAiDataProvider' );
 
 export default withAiDataProvider;
+
+type OptionsProps = {
+	/**
+	 * Array of block names to apply the data provider to.
+	 */
+	blocks: string[] | string;
+};
+
+/**
+ * Function that returns a High Order Component that provides the
+ * AI Assistant Data context to the wrapped component.
+ *
+ * Ideally though to use with the `editor.BlockListBlock` filter.
+ *
+ * @see https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/#editor-blocklistblock
+ * @param {OptionsProps} options - Options
+ * @param {string[]} options.blocks - Array of block names to apply the data provider to.
+ * @returns {ReactNode}          	  Wrapped component, populated with the AI Assistant Data context.
+ */
+export const blockListBlockWithAiDataProvider = ( options: OptionsProps = { blocks: [ '' ] } ) => {
+	return createHigherOrderComponent( ( WrappedComponent: ReactNode ) => {
+		return props => {
+			const blockName = props?.block?.name;
+			if ( ! blockName ) {
+				return <WrappedComponent { ...props } />;
+			}
+
+			/*
+			 * Extend only blocks that are specified in the blocks option.
+			 * `blocks` option accepts a string or an array of strings.
+			 */
+			const blockTypesToExtend = Array.isArray( options.blocks )
+				? options.blocks
+				: [ options.blocks ];
+
+			if ( ! blockTypesToExtend.includes( blockName ) ) {
+				return <WrappedComponent { ...props } />;
+			}
+
+			// Connect with the AI Assistant communication layer.
+			// @todo: this is a copy of the code above, we should refactor this.
+			const {
+				suggestion,
+				error: requestingError,
+				requestingState,
+				request: requestSuggestion,
+				stopSuggestion,
+				eventSource,
+			} = useAiSuggestions();
+
+			// Build the context value to pass to the ai assistant data provider.
+			const dataContextValue = useMemo(
+				() => ( {
+					suggestion,
+					requestingError,
+					requestingState,
+					eventSource,
+
+					requestSuggestion,
+					stopSuggestion,
+				} ),
+				[
+					suggestion,
+					requestingError,
+					requestingState,
+					eventSource,
+					requestSuggestion,
+					stopSuggestion,
+				]
+			);
+
+			return (
+				<AiDataContextProvider value={ dataContextValue }>
+					<WrappedComponent { ...props } />
+				</AiDataContextProvider>
+			);
+		};
+	}, 'blockListBlockWithAiDataProvider' );
+};

package/src/hooks/use-media-recording/index.ts

@@ -189,6 +189,15 @@ export default function useMediaRecording( {
 				throw err;
 			} );
 		return () => {
+			/*
+			 * mediaRecordRef is not defined when
+			 * the getUserMedia API is not supported,
+			 * or when the user has not granted access
+			 */
+			if ( ! mediaRecordRef?.current ) {
+				return;
+			}
+
 			mediaRecordRef.current.removeEventListener( 'start', onStartListener );
 			mediaRecordRef.current.removeEventListener( 'stop', onStopListener );
 			mediaRecordRef.current.removeEventListener( 'pause', onPauseListener );

package/src/suggestions-event-source/Readme.md

@@ -39,6 +39,7 @@ The constructor takes an object with the following properties:
     - `postId` (optional): The post ID.
     - `feature` (optional): A string that specifies the AI model to use (default or 'ai-assistant-experimental').
     - `fromCache` (optional): A boolean to indicate whether to fetch the response from cache.
+    - `model` (optional): Allows to use a specific AI model.
 
 ### Usage
 

package/src/suggestions-event-source/index.ts

@@ -12,6 +12,7 @@ import requestJwt from '../jwt';
  * Types & constants
  */
 import {
+	ERROR_CONTEXT_TOO_LARGE,
 	ERROR_MODERATION,
 	ERROR_NETWORK,
 	ERROR_QUOTA_EXCEEDED,
@@ -19,7 +20,12 @@ import {
 	ERROR_SERVICE_UNAVAILABLE,
 	ERROR_UNCLEAR_PROMPT,
 } from '../types';
-import type { PromptMessagesProp, PromptProp, SuggestionErrorCode } from '../types';
+import type {
+	AiModelTypeProp,
+	PromptMessagesProp,
+	PromptProp,
+	SuggestionErrorCode,
+} from '../types';
 
 type SuggestionsEventSourceConstructorArgs = {
 	url?: string;
@@ -30,6 +36,7 @@ type SuggestionsEventSourceConstructorArgs = {
 		feature?: 'ai-assistant-experimental' | string | undefined;
 		fromCache?: boolean;
 		functions?: Array< object >;
+		model?: AiModelTypeProp;
 	};
 };
 
@@ -47,16 +54,17 @@ const debug = debugFactory( 'jetpack-ai-client:suggestions-event-source' );
  * It also emits a 'suggestion' event with the full suggestion received so far
  *
  * @returns {EventSource} The event source
- * @fires suggestion                - The full suggestion has been received so far
- * @fires message                   - A message has been received
- * @fires chunk                     - A chunk of data has been received
- * @fires done                      - The stream has been closed. No more data will be received
- * @fires error                     - An error has occurred
- * @fires error_network             - The EventSource connection to the server returned some error
- * @fires error_service_unavailable - The server returned a 503 error
- * @fires error_quota_exceeded      - The server returned a 429 error
- * @fires error_moderation          - The server returned a 422 error
- * @fires error_unclear_prompt      - The server returned a message starting with JETPACK_AI_ERROR
+ * @fires SuggestionsEventSource#suggestion                - The full suggestion has been received so far
+ * @fires SuggestionsEventSource#message                   - A message has been received
+ * @fires SuggestionsEventSource#chunk                     - A chunk of data has been received
+ * @fires SuggestionsEventSource#done                      - The stream has been closed. No more data will be received
+ * @fires SuggestionsEventSource#error                     - An error has occurred
+ * @fires SuggestionsEventSource#error_network             - The EventSource connection to the server returned some error
+ * @fires SuggestionsEventSource#error_context_too_large   - The server returned a 413 error
+ * @fires SuggestionsEventSource#error_moderation          - The server returned a 422 error
+ * @fires SuggestionsEventSource#error_quota_exceeded      - The server returned a 429 error
+ * @fires SuggestionsEventSource#error_service_unavailable - The server returned a 503 error
+ * @fires SuggestionsEventSource#error_unclear_prompt      - The server returned a message starting with JETPACK_AI_ERROR
  */
 export default class SuggestionsEventSource extends EventTarget {
 	fullMessage: string;
@@ -103,6 +111,7 @@ export default class SuggestionsEventSource extends EventTarget {
 			question?: PromptProp;
 			feature?: string;
 			functions?: Array< object >;
+			model?: AiModelTypeProp;
 		} = {};
 
 		// Populate body data with post id
@@ -142,6 +151,12 @@ export default class SuggestionsEventSource extends EventTarget {
 			bodyData.functions = options.functions;
 		}
 
+		// Model
+		if ( options?.model?.length ) {
+			debug( 'Model: %o', options.model );
+			bodyData.model = options.model;
+		}
+
 		await fetchEventSource( url, {
 			openWhenHidden: true,
 			method: 'POST',
@@ -174,7 +189,7 @@ export default class SuggestionsEventSource extends EventTarget {
 				if (
 					response.status >= 400 &&
 					response.status <= 500 &&
-					! [ 422, 429 ].includes( response.status )
+					! [ 413, 422, 429 ].includes( response.status )
 				) {
 					this.processConnectionError( response );
 				}
@@ -189,12 +204,12 @@ export default class SuggestionsEventSource extends EventTarget {
 				}
 
 				/*
-				 * error code 429
-				 * you exceeded your current quota please check your plan and billing details
+				 * error code 413
+				 * request context too large
 				 */
-				if ( response.status === 429 ) {
-					errorCode = ERROR_QUOTA_EXCEEDED;
-					this.dispatchEvent( new CustomEvent( ERROR_QUOTA_EXCEEDED ) );
+				if ( response.status === 413 ) {
+					errorCode = ERROR_CONTEXT_TOO_LARGE;
+					this.dispatchEvent( new CustomEvent( ERROR_CONTEXT_TOO_LARGE ) );
 				}
 
 				/*
@@ -206,6 +221,15 @@ export default class SuggestionsEventSource extends EventTarget {
 					this.dispatchEvent( new CustomEvent( ERROR_MODERATION ) );
 				}
 
+				/*
+				 * error code 429
+				 * you exceeded your current quota please check your plan and billing details
+				 */
+				if ( response.status === 429 ) {
+					errorCode = ERROR_QUOTA_EXCEEDED;
+					this.dispatchEvent( new CustomEvent( ERROR_QUOTA_EXCEEDED ) );
+				}
+
 				// Always dispatch a global ERROR_RESPONSE event
 				this.dispatchEvent(
 					new CustomEvent( ERROR_RESPONSE, {

package/src/types.ts

@@ -1,6 +1,7 @@
 export const ERROR_SERVICE_UNAVAILABLE = 'error_service_unavailable' as const;
 export const ERROR_QUOTA_EXCEEDED = 'error_quota_exceeded' as const;
 export const ERROR_MODERATION = 'error_moderation' as const;
+export const ERROR_CONTEXT_TOO_LARGE = 'error_context_too_large' as const;
 export const ERROR_NETWORK = 'error_network' as const;
 export const ERROR_UNCLEAR_PROMPT = 'error_unclear_prompt' as const;
 export const ERROR_RESPONSE = 'error_response' as const;
@@ -9,6 +10,7 @@ export type SuggestionErrorCode =
 	| typeof ERROR_SERVICE_UNAVAILABLE
 	| typeof ERROR_QUOTA_EXCEEDED
 	| typeof ERROR_MODERATION
+	| typeof ERROR_CONTEXT_TOO_LARGE
 	| typeof ERROR_NETWORK
 	| typeof ERROR_UNCLEAR_PROMPT
 	| typeof ERROR_RESPONSE;
@@ -17,7 +19,7 @@ export type SuggestionErrorCode =
  * Prompt types
  */
 export type PromptItemProps = {
-	role: 'system' | 'user' | 'assistant';
+	role: 'system' | 'user' | 'assistant' | 'jetpack-ai';
 	content?: string;
 	context?: object;
 };
@@ -35,7 +37,6 @@ export type { RequestingErrorProps } from './hooks/use-ai-suggestions';
 /*
  * Requests types
  */
-
 const REQUESTING_STATE_INIT = 'init' as const;
 const REQUESTING_STATE_REQUESTING = 'requesting' as const;
 const REQUESTING_STATE_SUGGESTING = 'suggesting' as const;
@@ -51,3 +52,11 @@ export const REQUESTING_STATES = [
 ] as const;
 
 export type RequestingStateProp = ( typeof REQUESTING_STATES )[ number ];
+
+/*
+ * Model types and constants
+ */
+export const AI_MODEL_GPT_3_5_Turbo_16K = 'gpt-3.5-turbo-16k' as const;
+export const AI_MODEL_GPT_4 = 'gpt-4' as const;
+
+export type AiModelTypeProp = typeof AI_MODEL_GPT_3_5_Turbo_16K | typeof AI_MODEL_GPT_4;