@automattic/jetpack-ai-client 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.1] - 2023-08-01
+### Added
+- Add AI Client icon components [#32079]
+- AI Assistant: add function calling feature. [#32161]
+- AI Client: add AI Assistant data context. [#32129]
+- AI Client: add useAiContext() react hook. [#32145]
+- AI Client: add useAiSuggestions() react custom hook. [#32022]
+- AI Client: introduce AI Control component. [#32163]
+- AI Client: introduce withAiDataProvider HOC. [#32142]
+
+### Changed
+- AI Client: add Icon suffix to icon components. [#32173]
+- AI Client: handle properly passing the post_id parameter to endpoint. [#32104]
+- AI Client: replace using CSS modules with the regular way. [#32171]
+
+### Removed
+- AI Client: remove unused image library [#32127]
+
 ## 0.1.0 - 2023-07-25
 ### Added
 - Add Jetpack AI Client [#30855]
@@ -17,3 +35,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31468]
 - Updated package dependencies. [#31659]
 - Updated package dependencies. [#31785]
+
+[0.1.1]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.0...v0.1.1

package/index.ts

@@ -1,4 +1,26 @@
+/*
+ * Core library exports
+ */
 export { default as requestJwt } from './src/jwt';
 export { default as SuggestionsEventSource } from './src/suggestions-event-source';
 export { default as askQuestion } from './src/ask-question';
-export * from './src/index.js';
+
+/*
+ * Hooks
+ */
+export { default as useAiSuggestions } from './src/hooks/use-ai-suggestions';
+
+/*
+ * Components: Icons
+ */
+export * from './src/icons';
+
+/*
+ * Components
+ */
+export { default as AIControl } from './src/components/ai-control';
+
+/*
+ * Contexts
+ */
+export * from './src/data-flow';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "@automattic/jetpack-ai-client",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "A JS client for consuming Jetpack AI services",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/ai-client/#readme",
 	"bugs": {
@@ -21,7 +21,8 @@
 	},
 	"type": "module",
 	"devDependencies": {
-		"jest": "*",
+		"@storybook/react": "7.1.0",
+		"jest": "^29.6.2",
 		"jest-environment-jsdom": "29.5.0",
 		"typescript": "5.0.4"
 	},
@@ -33,6 +34,15 @@
 		"@automattic/jetpack-shared-extension-utils": "^0.10.9",
 		"@microsoft/fetch-event-source": "2.0.1",
 		"@wordpress/api-fetch": "6.34.0",
-		"debug": "4.3.4"
+		"@wordpress/block-editor": "12.5.0",
+		"@wordpress/components": "25.3.0",
+		"@wordpress/data": "9.7.0",
+		"@wordpress/element": "5.14.0",
+		"@wordpress/i18n": "4.37.0",
+		"@wordpress/icons": "9.28.0",
+		"classnames": "2.3.2",
+		"debug": "4.3.4",
+		"react": "18.2.0",
+		"react-dom": "18.2.0"
 	}
 }

package/src/ask-question/Readme.md

@@ -11,7 +11,7 @@ function askQuestion(
 ): Promise< SuggestionsEventSource >
 ```
 
-## Parameters
+<h2 id="ask-question-parameters">Parameters</h2>
 
 - `question` (**string** | **PromptItemProps[]**):
     - The question to ask. 

package/src/ask-question/index.ts

@@ -7,9 +7,9 @@ import SuggestionsEventSource from '../suggestions-event-source';
 /*
  * Types & constants
  */
-import type { PromptItemProps } from '../types';
+import type { PromptProp } from '../types';
 
-type AskQuestionOptionsArgProps = {
+export type AskQuestionOptionsArgProps = {
 	/*
 	 * ID of the post where the question is asked.
 	 */
@@ -24,6 +24,16 @@ type AskQuestionOptionsArgProps = {
 	 * Allows to use a specific AI assistant feature. Default value is undefined.
 	 */
 	feature?: 'ai-assistant-experimental' | string | undefined;
+
+	/*
+	 * Allows the use of function calling. Default value is undefined.
+	 */
+	functions?: Array< {
+		name?: string;
+		arguments?: string;
+		// eslint-disable-next-line @typescript-eslint/ban-types
+		implementation?: Function;
+	} >;
 };
 
 const debug = debugFactory( 'jetpack-ai-client:ask-question' );
@@ -32,7 +42,7 @@ const debug = debugFactory( 'jetpack-ai-client:ask-question' );
  * An asynchronous function that asks a question
  * and returns an event source with suggestions.
  *
- * @param {string|PromptItemProps[]} question - The question to ask. It can be a simple string or an array of PromptItemProps objects.
+ * @param {PromptProp} question - The question to ask. It can be a simple string or an array of PromptMessageItemProps objects.
  * @param {AskQuestionOptionsArgProps} options - An optional object for additional configuration:
  * @returns {Promise<SuggestionsEventSource>}    A promise that resolves to an instance of the SuggestionsEventSource
  * @example
@@ -47,12 +57,16 @@ const debug = debugFactory( 'jetpack-ai-client:ask-question' );
  *  } );
  */
 export default async function askQuestion(
-	question: string | PromptItemProps[],
-	{ postId = null, fromCache = false, feature }: AskQuestionOptionsArgProps = {}
+	question: PromptProp,
+	{ postId = null, fromCache = false, feature, functions }: AskQuestionOptionsArgProps = {}
 ): Promise< SuggestionsEventSource > {
-	debug( 'Asking question: %o. options: %o', question, { postId, fromCache, feature } );
+	debug( 'Asking question: %o. options: %o', question, { postId, fromCache, feature, functions } );
 
 	const { token } = await requestJwt();
 
-	return new SuggestionsEventSource( { question, token, options: { postId, feature, fromCache } } );
+	return new SuggestionsEventSource( {
+		question,
+		token,
+		options: { postId, feature, fromCache, functions },
+	} );
 }

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

@@ -0,0 +1,130 @@
+/**
+ * External dependencies
+ */
+import { PlainText } from '@wordpress/block-editor';
+import { Button, Spinner } from '@wordpress/components';
+import { useRef } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { Icon, closeSmall, check, arrowUp } from '@wordpress/icons';
+import classNames from 'classnames';
+/**
+ * Internal dependencies
+ */
+import { aiAssistantIcon } from '../../icons';
+import './style.scss';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = () => {};
+
+/**
+ * AI Control component.
+ *
+ * @param {object} props - component props
+ * @param {boolean} props.loading - loading state
+ * @param {string} props.value - input value
+ * @param {string} props.placeholder - input placeholder
+ * @param {boolean} props.showAccept - show accept button
+ * @param {string} props.acceptLabel - accept button label
+ * @param {boolean} props.showButtonsLabel - show buttons label
+ * @param {boolean} props.isOpaque - is opaque
+ * @param {Function} props.onChange - input change handler
+ * @param {Function} props.onSend - send request handler
+ * @param {Function} props.onStop - stop request handler
+ * @param {Function} props.onAccept - accept handler
+ * @returns {object} - AI Control component
+ */
+export default function AIControl( {
+	loading = false,
+	value = '',
+	placeholder = '',
+	showAccept = false,
+	acceptLabel = __( 'Accept', 'jetpack-ai-client' ),
+	showButtonsLabel = true,
+	isOpaque = false,
+	onChange = noop,
+	onSend = noop,
+	onStop = noop,
+	onAccept = noop,
+}: {
+	loading?: boolean;
+	value: string;
+	placeholder?: string;
+	showAccept?: boolean;
+	acceptLabel?: string;
+	showButtonsLabel?: boolean;
+	isOpaque?: boolean;
+	onChange: ( newValue: string ) => void;
+	onSend: ( currentValue: string ) => void;
+	onStop: () => void;
+	onAccept: () => void;
+} ) {
+	const promptUserInputRef = useRef( null );
+
+	return (
+		<div className="jetpack-components-ai-control__container">
+			<div
+				className={ classNames( 'jetpack-components-ai-control__wrapper', {
+					'is-opaque': isOpaque,
+				} ) }
+			>
+				<div className="jetpack-components-ai-controlton__icon">
+					{ loading ? (
+						<Spinner className="input-spinner" />
+					) : (
+						<Icon className="input-icon" icon={ aiAssistantIcon } size={ 24 } />
+					) }
+				</div>
+
+				<PlainText
+					value={ value }
+					onChange={ onChange }
+					placeholder={ placeholder }
+					className="jetpack-components-ai-control__input"
+					disabled={ loading }
+					ref={ promptUserInputRef }
+				/>
+
+				<div className="jetpack-components-ai-control__controls">
+					<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
+						{ ! loading ? (
+							<Button
+								className="jetpack-components-ai-control__controls-prompt_button"
+								onClick={ () => onSend( value ) }
+								isSmall={ true }
+								disabled={ value?.length }
+								label={ __( 'Send request', 'jetpack-ai-client' ) }
+							>
+								<Icon icon={ arrowUp } />
+								{ showButtonsLabel && __( 'Send', 'jetpack-ai-client' ) }
+							</Button>
+						) : (
+							<Button
+								className="jetpack-components-ai-control__controls-prompt_button"
+								onClick={ onStop }
+								isSmall={ true }
+								label={ __( 'Stop request', 'jetpack-ai-client' ) }
+							>
+								<Icon icon={ closeSmall } />
+								{ showButtonsLabel && __( 'Stop', 'jetpack-ai-client' ) }
+							</Button>
+						) }
+					</div>
+
+					{ showAccept && (
+						<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
+							<Button
+								className="jetpack-components-ai-control__controls-prompt_button"
+								onClick={ onAccept }
+								isSmall={ true }
+								label={ acceptLabel }
+							>
+								<Icon icon={ check } />
+								{ acceptLabel }
+							</Button>
+						</div>
+					) }
+				</div>
+			</div>
+		</div>
+	);
+}

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

@@ -0,0 +1,42 @@
+/**
+ * External dependencies
+ */
+import { useState } from '@wordpress/element';
+import React from 'react';
+/**
+ * Internal dependencies
+ */
+import AIControl from '../index';
+/**
+ * Types
+ */
+import type { Meta } from '@storybook/react';
+
+export default {
+	title: 'JS Packages/AI Client/AI Control',
+	component: AIControl,
+	parameters: {},
+} as Meta< typeof AIControl >;
+
+const Template = args => {
+	const [ value, setValue ] = useState( '' );
+
+	const handleChange = ( newValue: string ) => {
+		setValue( newValue );
+		args?.onChange?.( newValue );
+	};
+
+	return <AIControl { ...args } onChange={ handleChange } value={ args?.value ?? value } />;
+};
+
+const DefaultArgs = {
+	loading: false,
+	isOpaque: false,
+	placeholder: '',
+	showButtonsLabel: true,
+	showAccept: false,
+	acceptLabel: 'Accept',
+};
+
+export const Default = Template.bind( {} );
+Default.args = DefaultArgs;

package/src/components/ai-control/style.scss

@@ -0,0 +1,107 @@
+.jetpack-components-ai-control__container {
+	color: var( --jp-gray-80 );
+	background-color: var( --jp-white );
+	box-shadow: var( --wp--preset--color--cyan-bluish-gray ) 0px 0px 0px 1px, var( --wp--preset--color--cyan-bluish-gray ) 0px 0px 8px;
+	font-family: "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
+}
+
+.jetpack-components-ai-control__wrapper {
+	display: flex;
+	padding: 12px 14px;
+	gap: 8px;
+
+	&.is-opaque {
+		opacity: 0.4;
+	}
+
+	textarea.jetpack-components-ai-control__input {
+		width: 100%;
+        min-height: 20px;
+		flex-grow: 1;
+		border-radius: 2px;
+		padding: 6px 8px;
+
+		resize: none !important;
+		border: none;
+		box-shadow: none;
+		color: var( --jp-gray-80 );
+
+		font-size: 16px;
+		font-weight: 400;
+		line-height: 20px;
+
+		transition: box-shadow 0.1s linear 0s;
+
+		&:focus {
+			box-shadow: none;
+			color: var( --jp-gray-80 );
+		}
+
+		@media (min-width: 600px) {
+			font-size: 13px;
+		}
+
+		&::placeholder {
+			text-overflow: ellipsis;
+			white-space: nowrap;
+			opacity: 0.75;
+		}
+	}
+}
+
+.jetpack-components-ai-controlton__icon {
+	flex-shrink: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	
+	.input-icon {
+		// Brand green regardless of theme
+		color: var( --jp-green-40 );
+	}
+	
+	.input-spinner {
+		margin: 0;
+		width: 24px;
+		height: 24px;
+
+		path {
+			color: var( --jp-green-40 );
+		}
+	}
+}
+
+.jetpack-components-ai-control__controls {
+	display: flex;
+	align-items: center;
+}
+
+.jetpack-components-ai-control__controls-prompt_button_wrapper {
+	text-transform: uppercase;
+	font-size: 11px;
+	font-weight: 600;
+	line-height: 16px;
+	user-select: none;
+	white-space: nowrap;
+	display: flex;
+	align-items: center;
+}
+
+.jetpack-components-ai-control__controls-prompt_button {
+	color: var( --jp-gray-80 );
+	text-transform: uppercase;
+
+	> SVG {
+		margin-right: 4px;
+	}
+
+	&:hover,
+	&:active {
+		color: var( --wp-components-color-accent, var( --wp-admin-theme-color ) );
+	}
+
+	&:disabled {
+		opacity: 0.6;
+		cursor: not-allowed;
+	}
+}

package/src/data-flow/Readme.md

@@ -0,0 +1,113 @@
+
+# AI Assistant Data Flow
+
+```jsx
+import { withAiAssistantData, useAiContext } from '@automattic/jetpack-ai-client';
+
+const MyComponent = () => {
+  const { suggestion, requestingState, requestSuggestion } = useAiContext( {
+    onDone: content => console.log( `Content is done: ${ content }.` );
+  } );
+
+  return (
+    <>
+      <div>{ suggestions }</div>
+      <button
+        onClick={ () => requestSuggestion( 'How to make a cake' ) }
+        disabled={ requestingState === 'suggesting' }
+      >
+        Request
+      </button>
+    <>
+  )
+};
+
+// Ensure to provide the data context to `MyComponent`.
+export default withAiAssistantData( MyComponent );
+
+```
+
+## In-depth Analysis
+
+* [AI Data Context](#ai-assistant-content)
+* [withAiDataProvider HOC](#with-ai-data-provider)
+* [useAiContext Hook](#use-ai-context)
+
+<h2 id="ai-assistant-content">Ai Data Context</h2>
+
+The Ai Data Context is a React context implementation for managing the state and functionality of an AI Assistant. It manages the suggestion values, error states, and request functionality.
+
+
+### Usage
+
+Import the Ai Data Context and Provider into your component:
+
+```javascript
+import { AiDataContext, AiDataContextProvider } from '@automattic/jetpack-ai-client';
+```
+
+Use the Provider in your component's render method to wrap the children components:
+
+```es6
+<AiDataContextProvider value={ value }>
+  { children }
+</AiDataContextProvider>
+```
+
+You can access the context values in your child components using the `useContext` hook:
+
+```javascript
+const aiContext = React.useContext( AiDataContext );
+```
+
+### Context Values
+
+The Ai Data Context has the following values:
+
+#### `suggestion`
+The suggestion value from the AI.
+
+#### `requestingError`
+The error object returned from the AI suggestion request. It contains the following properties:
+- `code`: A code referring to the type of error. The possible error codes are `ERROR_SERVICE_UNAVAILABLE`, `ERROR_QUOTA_EXCEEDED`, `ERROR_MODERATION`, `ERROR_NETWORK`, `ERROR_UNCLEAR_PROMPT`.
+- `message`: A user-friendly error message.
+- `severity`: The severity of the error. It can either be 'info' or 'error'.
+
+#### `requestingState`
+The current state of the suggestion request. It can be one of the following:
+- `init`: The initial state before a request is made.
+- `requesting`: The state when a request is being made.
+- `suggesting`: The state when the AI is generating a suggestion.
+- `done`: The state when a suggestion has been received.
+- `error`: The state when an error has occurred during the request.
+
+#### `requestSuggestion`
+A function to request a suggestion from the AI. The function takes a prompt parameter which can be an object of `PromptMessagesProp` or a string.
+
+<h2 id="with-ai-data-provider">withAiDataProvider HOC</h2>
+
+Higher Order Component (HOC) that wraps a given component and provides it with the AI Assistant Data context. This HOC is instrumental in the data flow of the AI Assistant functionality and helps manage the interaction with the AI Assistant's communication layer.
+
+<h2 id="use-ai-context">useAiContext Hook</h2>
+
+The `useAiContext` hook provides a convenient way to access the 
+Ai Data Context and subscribe to the `done` and `suggestion` events emitted by SuggestionsEventSource.
+
+```es6
+const { suggestion } = useAiContext( {
+  onDone: content => console.log( content ),
+  onSuggestion: suggestion => console.log( suggestion ),
+} );
+
+```
+
+_Before using the hook, ensure the data is provided by the [Ai Data Context](#ai-assistant-content). [withAiDataProvider HOC](#with-ai-data-provider) is usually the best option_
+
+Optional options object:
+
+- `onDone`: A callback function to be called when a request completes. The callback receives the request result as a parameter.
+- `onSuggestion`: A callback function to be called when a new suggestion is received. The callback receives the suggestion as a parameter.
+
+These callbacks will be invoked with the detail of the corresponding event emitted by SuggestionsEventSource.
+
+When called, the hook returns the Ai Data Context.

package/src/data-flow/context.tsx

@@ -0,0 +1,74 @@
+/**
+ * External dependencies
+ */
+import { createContext } from '@wordpress/element';
+import React from 'react';
+/**
+ * Types & Constants
+ */
+import SuggestionsEventSource from '../suggestions-event-source';
+import type { RequestingStateProp, RequestingErrorProps } from '../hooks/use-ai-suggestions';
+import type { PromptProp } from '../types';
+
+export type AiDataContextProps = {
+	/*
+	 * Suggestion value
+	 */
+	suggestion: string;
+
+	/*
+	 * Suggestion error
+	 */
+	requestingError: RequestingErrorProps;
+
+	/*
+	 * Requesting state
+	 */
+	requestingState: RequestingStateProp;
+
+	/*
+	 * Request suggestion function
+	 */
+	requestSuggestion: ( prompt: PromptProp ) => void;
+
+	/*
+	 * The Suggestions Event Source instance
+	 */
+	eventSource: SuggestionsEventSource | null;
+};
+
+type AiDataContextProviderProps = {
+	/*
+	 * Data to provide to the context
+	 */
+	value: AiDataContextProps;
+
+	/*
+	 * Children
+	 */
+	children: React.ReactNode;
+};
+
+/**
+ * AI Data Context
+ *
+ * @returns {AiDataContextProps} Context.
+ */
+export const AiDataContext = createContext( {} as AiDataContextProps );
+
+/**
+ * AI Data Context Provider
+ *
+ * @param {AiDataContextProviderProps} props - Component props.
+ * @returns {React.ReactNode}                           Context provider.
+ * @example
+ * <AiDataContextProvider value={ value }>
+ * 	{ children }
+ * </AiDataContextProvider>
+ */
+export const AiDataContextProvider = ( {
+	value,
+	children,
+}: AiDataContextProviderProps ): React.ReactNode => (
+	<AiDataContext.Provider value={ value } children={ children } />
+);

package/src/data-flow/index.ts

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