@sanity/assist 1.2.14 → 1.2.15-lang.1

package/README.md

@@ -16,8 +16,14 @@
   - [Disable for a field](#disable-for-a-field)
   - [Disable for an array type](#disable-for-an-array-type)
   - [Unsupported types](#unsupported-types)
+  - [Reference support](#reference-support)
   - [Troubleshooting](#troubleshooting)
 - [Included document types](#included-document-types)
+- [Field and type filters](#field-and-type-filters)
+- [Caption generation](#caption-generation)
+- [Full document translation](#full-document-translation)
+  - [What it solves](#what-ai-assist-full-document-translations-solves)
+  - [Configure](#configure-document-translations)
 - [License](#license)
 - [Develop \& test](#develop--test)
   - [Release new version](#release-new-version)
@@ -167,13 +173,13 @@ defineType({
 
 The following types are not supported, and behave as excluded types:
 * [Number](https://www.sanity.io/docs/number-type)
-* [Reference](https://www.sanity.io/docs/reference-type)
 * [Slug](https://www.sanity.io/docs/slug-type)
 * [Url](https://www.sanity.io/docs/url-type)
 * [Date](https://www.sanity.io/docs/date-type)
 * [Datetime](https://www.sanity.io/docs/datetime-type)
 * [Image](https://www.sanity.io/docs/image-type) (supported when image has custom fields)
 * [File](https://www.sanity.io/docs/file-type) (never supported, even when file has custom fields)
+* [Reference](https://www.sanity.io/docs/reference-type) (supported when configured with embeddingsIndex)
 
 Types and fields with `hidden` or `readonly` with a truthy value (`true` or `function`) are not supported.
 (Hidden and readOnly fields can be referenced in instructions still)
@@ -183,6 +189,44 @@ Fields with these types will not be changed by the assistant, do not have AI Ass
 Objects where all fields are excluded or unsupported and arrays where all member types are excluded or unsupported
 will also be excluded.
 
+### Reference support
+
+#### Create an Embeddings-index
+To enable AI assist for references, first, your project must have an existing [embeddings-index](https://www.sanity.io/docs/embeddings-index-api-overview)
+with the documents it should be able to reference.
+
+You can manage your indexes directly in the studio using the [Embeddings Index Dashboard plugin](https://github.com/sanity-io/embeddings-index-ui#embeddings-index-api-dashboard-for-sanity-studio).
+
+#### Set schema options
+Set `options.aiWritingAssistance.embeddingsIndex` for reference fields/types you want to enable reference instructions for. 
+Reference fields with this options set can have instructions attached to them, and will be visited when running instructions for object fields and arrays.
+
+AI assist will use the embeddings-index, filtered by the types allowed by the reference to look up contextually relevant references.
+For arrays or portable text fields with references, one more references can be added. Use the instruction text to control this.
+
+Example:
+
+```ts
+import {defineArrayMember} from 'sanity'
+
+defineField({
+  type: 'reference',
+  name: 'articleReference',
+  title: 'Article referene',
+  to: [ { type: 'article'} ],
+  options: {
+    aiWritingAssistance: {
+      embeddingsIndex: 'article-index'
+    },
+  },
+})
+```
+
+An example instruction attached to this field could be:
+`Given <Document field: Title> suggest a related article`
+
+Running it would use the `article-index` to find an related article based on the current document title.
+
 ### Troubleshooting
 
 There are limits to how much text the AI can process when processing an instruction. Under the hood, the AI Assist will add information about your schema, which adds to what's commonly referred to as “the context window.”
@@ -191,6 +235,8 @@ If you have a very large schema (that is, many document and field types), it can
 
 We recommend excluding any and all types which rarely would benefit from automated workflows. A quick win is typically to exclude array types. It can be a good idea to exclude most non-block types from Portable Text arrays. This will ensure that the Sanity Assist outputs mostly formatted text.
 
+It is also possible to exclude fields/types when creating an instruction. See [Field and type filters](#field-and-type-filters) for more. 
+
 ## Included document types
 
 This plugin adds an `AI Context` document type. 
@@ -206,6 +252,351 @@ import {contextDocumentTypeName} from '@sanity/assist'
 S.documentTypeListItem(contextDocumentTypeName)
 ```
 
+## Field and type filters
+
+When creating instructions for a document, objects fields, array fields or portable text fields, you can explicitly control what will be visited by AI Assist.
+By default, all fields and types configured for assist will be included. 
+
+Opting out fields/types per instruction is done using the respective field/type filter checkboxes under the instruction.
+When using these filters, it is not necessary to tell Assist what to include in the instruction text itself.  
+
+Note that if the schema targeted by the instruction changes, the following behavior applies:
+* instructions that included all fields or types will automatically also include the new fields or types
+* instructions that have excluded one or more fields or types, will NOT include the new fields or types
+
+## Caption generation
+AI Assist can optionally generate captions for images. This has to be enabled on an image-type/field,
+by setting the `options.captionField` on the image type, where `captionField` is the field name of a
+custom string-field on the image object:
+
+## Full document translation
+AI assist offers full document translations, which is ideal for pairing with [@sanity/document-internationalization](https://github.com/sanity-io/document-internationalization).
+
+### What AI Assist full document translations solves
+
+Given a document written in one language, AI assist can translate the document in place to a language specified by a language field in the document.
+
+When the document translation feature is enabled, AI Assist will go through the document field by field, translating all string and portable text fields into the language specified in the document's language field.
+
+This works well with [@sanity/document-internationalization](https://github.com/sanity-io/document-internationalization), where documents are duplicated from a source language and set a hidden language field.
+
+AI assist allows editors to translate these documents into the desired language immediately.
+
+### Configure document translations
+
+To enable full document translations, set `translate.document.languageField` to the path of the language field in your documents.
+
+All documents with a language field will get a "Translate document" instruction added to the assist drop-down for the document.
+
+To limit which document types get "Translate document" further, provide `translate.document.documentTypes` with an array of document type names.
+
+If the studio is using [@sanity/document-internationalization](https://github.com/sanity-io/document-internationalization), these options should be the same as those used for that plugin.
+
+**Example configs**
+
+```ts
+// This will add a "Translate document" instruction to all documents with a language field
+assist({
+    translate: {
+        document: {
+            languageField: 'language'
+        }
+    }
+})
+```
+
+```ts
+// This will add a "Translate document" instruction only to the 'article' document type
+assist({
+    translate: {
+        document: {
+            languageField: 'language',
+            documentTypes: ['article']
+        }
+    }
+})
+```
+
+**All configuration params**
+```ts
+assist({
+    translate: {
+        /** Config for document types with a single language field that determines the language for the whole document. */
+        document: {
+            /**
+             * Required config, enable document tranlations.
+             *
+             * Path to language field in documents. Can be a hidden field.
+             * For instance: 'config.language'
+             *
+             * For projects that use the `@sanity/document-internationalization` plugin,
+             * this should be the same as `languageField` config for that plugin (which defaults to 'language')
+             */
+            languageField: string,
+
+            /**
+             * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+             *
+             * this property will add a translate instruction to these document types if defined.
+             * If undefined, the instruction will be added to all documents with aiAssistance enabled and a field matching `languageField` config.
+             *
+             * Documents with translation support will get a "Translate document>" instruction added.
+             **/
+            documentTypes: string[]
+        }
+    }
+})
+```
+
+## Field level translations
+
+AI assist offers field-level translations, which is ideal for using alongside with[sanity-plugin-internationalized-array](https://github.com/sanity-io/sanity-plugin-internationalized-array?tab=readme-ov-file#sanity-plugin-internationalized-array) and (@sanity/language-filter)[https://github.com/sanity-io/language-filter]
+
+### What AI Assist field-level translations solves
+
+Given a document with field values in different languages, AI assist can transfer and translate from one language to the others.
+
+The typical use case would be for documents that use internationalized wrapper types to hold values for multiple languages.
+
+AI Assist supports complex values, so language fields that hold nested objects, portable text, or arrays will also be translated.
+
+When initiating translations, editors select a language to translate from and which languages to translate to. This means that AI Assist supports partial translations in cases where editors are responsible for only some languages in the document.
+
+### Configure field translations
+To enable field-level translations, set `translate.field.documentTypes` to an array with which document types should get field translations, and `translate.field.languages`
+
+```ts
+assist({
+      translate: {
+        field: {
+          documentTypes: ['article'],
+          languages: [
+						{id: 'en', title: 'English'},
+						{id: 'de', title: 'German'}
+					]
+        },
+      },
+ })
+```
+
+These documents will get a "Translate fields" instruction added to the document AI Assist dropdown.
+
+Out of the box, this is sufficient config for document types using `internationalizedArray*` types for localization [sanity-plugin-internationalized-array](https://github.com/sanity-io/sanity-plugin-internationalized-array?tab=readme-ov-file#sanity-plugin-internationalized-array).
+
+It will also work without further config for object types named "locale*", with one field per language:
+
+*Example locale object supported by default*
+
+```ts
+// Object type with name starting with 'locale', and one field per language language
+defineType({
+	type: 'object',
+  name: 'localeString',
+  fields: [
+		defineField({
+      // these do not have to be string, could be any type
+			type: 'string',
+      name: 'en',
+			title: 'English'
+		}),
+		defineField({
+			type: 'string',
+      name: 'de',
+			title: 'German'
+		})
+	]
+})
+```
+
+**If your schema is not using either of these structures**, confer [Custom language fields](#custom-language-fields).
+
+### Loading field languages
+Languages must be an array of objects with an id and title.
+
+```ts
+assist({
+      translate: {
+        field: {
+          languages: [
+						{id: 'en', title: 'English'},
+						{id: 'de', title: 'German'}
+					]
+        },
+      },
+ })
+```
+
+Or an asynchronous function that returns an array of objects with an id and title.
+
+```ts
+assist({
+      translate: {
+        field: {
+          languages: async () => {
+					  const response = await fetch('https://example.com/languages')
+					  return response.json()
+					}
+        },
+      },
+ })
+```
+
+The async function contains a configured Sanity Client in the first parameter, allowing you to store Language options as documents. Your query should return an array of objects with an id and title.
+
+
+```ts
+assist({
+      translate: {
+        field: {
+          languages: async () => {
+					    const response = await client.fetch(`*[_type == "language"]{ id, title }`)
+						  return response
+					}
+        },
+      },
+ })
+```
+
+Additionally, you can "pick" fields from a document, to pass into the query. For example, if you have a concept of "Markets" where only certain language fields are required in certain markets.
+
+In this example, each language document has an array of strings called markets to declare where that language can be used. And the document being authored has a single market field.
+
+```ts
+assist({
+      translate: {
+        field: {
+          selectLanguageParams: {
+					  market: 'market'
+					},
+					languages: async (client, {market = ``}) => {
+					  const response = await client.fetch(
+							`*[_type == "language" && $market in markets]{ id, title }`,
+					    {market}
+					  )
+					  return response
+					},
+        },
+      },
+ })
+```
+
+### Custom language fields
+By providing a function to `translate.field.translationOutputs`, complete control over which fields belong to which language is given.
+
+`translationOutputs` is used when an editor uses the "Translate fields" instruction.
+
+It determines the relationships between document paths: Given a document path and a language, it should return into which sibling paths translations are output.
+
+`translationOutputs` is invoked once per path in the document (limited to a depth of 6), with the following:
+
+* `documentMember` - the field or array item for a given path; contains the path and its schemaType,
+* `enclosingType` - the schema type of the parent holding the member
+* `translateFromLanguageId` - the languageId for the language the users want to to translate from
+* `translateToLanguageIds` - all languageIds the user can translate to
+
+The function should return a `TranslationOutput[]` array that contains all the paths where translations from `documentMember` (in the language given by translateFromLanguageId) should be output.
+
+The function should return `undefined` for all documentMembers that should not be directly translated, or are nested fields under a translated path.
+
+#### Default function
+
+The default `translationOutputs` is available using `import {defaultTranslationOutputs} from '@sanity/assist`.
+
+#### Example
+
+Given the following document:
+
+```ts
+{
+	titles: {
+		_type: 'languageObject',		
+		en: {
+			_type: 'titleObject',
+			title: 'Some title',
+      subtitle: 'Some subtitle'
+		},
+		de: {
+			_type: 'titleObject',
+		}
+	}
+}
+```
+
+When translating from English to German, `translationOutputs` will be
+invoked multiple times.
+
+The following parameters will be the same every invocation:
+
+* `translateFromLanguageId` will be `'en'`
+* `translateToLanguageIds` will be `['de']`
+
+`documentMember` and `enclosingType` will change between each invocation, and take the following values:
+
+1. `{path: 'titles', name: 'titles', schemaType: ObjectSchemaType}`, `ObjectSchemaType`
+2. `{path: 'titles.en', name: 'en', schemaType: ObjectSchemaType}`, `ObjectSchemaType`
+3. `{path: 'titles.en.title', name: 'title', schemaType: StringSchemaType}`, `ObjectSchemaType`
+4. `{path: 'titles.en.subtitle', name: 'subtitle', schemaType: StringSchemaType}`, `ObjectSchemaType`
+5. `{path: 'titles.de', name: 'de', schemaType: ObjectSchemaType}`, `ObjectSchemaType`
+
+To indicate that you want everything under `title.en` to be translated into `title.de`, `translationOutputs` needs to return [id: 'de', outputPath: 'titles.de'] when invoked with `documentMember.path: 'titles.en'`.
+
+The following function enables this:
+
+```ts
+function translationOutputs(member, enclosingType, translateFromLanguageId, translateToLanguageIds) {
+  const parentIsLanguageWrapper = enclosingType.jsonType === 'object' && enclosingType.name.startsWith('language')
+
+	if (parentIsLanguageWrapper && translateFromLanguageId === member.name) {
+
+    // [id: 'de', ]
+		return translateToLanguageIds.map((translateToId) => ({
+								id: translateToId,
+                // in this example, member.path is 'titles.en' 	
+								// so this changes titles.en -> titles.de
+		            outputPath: [...member.path.slice(0, -1), translateToId],
+		       }))
+	}
+
+  // ignore other members 
+	return undefined
+}
+```
+
+### Full field translation configuration example
+
+```ts
+assist({
+      translate: {
+        field: {
+          documentTypes: ['article'],
+          selectLanguageParams: {market: 'market'},
+					apiVersion: '2023-01-01',
+					languages: (client, {market}) => {
+            return client.fetch(
+								`*[_type == "language" && $market in markets]{ id, title }`,
+							  {market}
+					  )
+          },
+					translationOutputs: (member, enclosingType, fromLanguageId, toLanguageIds) => {
+					   // When the document member is named the same as fromLangagueId
+             // and it is a field in a object with a name starting with "language"
+             // then we return the paths to all other sibling language fields (and their langauge id)
+						// It is ok that the member is an object, then all child fields will be translated
+							if (translateFromLanguageId === member.name && enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale')) {
+					      return translateToLanguageIds.map((translateToId) => ({
+					         id: translateToId,
+									 	//changes path.to.en -> path.to.de (for instance)
+					         outputPath: [...member.path.slice(0, -1), translateToId],
+					   }))
+					   }
+						// all other member paths are skipped
+				   return undefined
+				 }
+        },
+      },
+ })
+```
+
 ## Caveats
 
 Large Language Models (LLMs) are a new technology. Constraints and limitations are still being explored, 
@@ -215,12 +606,7 @@ but some common caveats to the field that you may run into using AI Assist are:
 * Timeouts: To be able to write structured content, we're using the largest language models - long-running results may time out or intermittently fail
 * Limited capacity: The underlying LLM APIs used by AI Assist are resource constrained
 
-## Other features
 
-### Caption generation
-AI Assist can optionally generate captions for images. This has to be enabled on an image-type/field,
-by setting the `options.captionField` on the image type, where `captionField` is the field name of a 
-custom string-field on the image object:
 
 ```tsx
 defineField({

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import {JSX as JSX_2} from 'react/jsx-runtime'
+import {Path} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
-import {SanityClient} from '@sanity/client'
+import {SanityClient} from 'sanity'
+import {SanityClient as SanityClient_2} from '@sanity/client'
+import {SchemaType} from 'sanity'
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
 
@@ -12,6 +15,7 @@ export declare interface AssistOptions {
 }
 
 declare interface AssistPluginConfig {
+  translate?: TranslationConfig
   /**
    * Set this to false to disable model migration from the alpha version of this plugin
    */
@@ -19,13 +23,166 @@ declare interface AssistPluginConfig {
   /**
    * @internal
    */
-  __customApiClient?: (defaultClient: SanityClient) => SanityClient
+  __customApiClient?: (defaultClient: SanityClient_2) => SanityClient_2
 }
 
 export declare const contextDocumentTypeName: 'assist.instruction.context'
 
+declare interface DocumentMember {
+  schemaType: SchemaType
+  path: Path
+  name: string
+}
+
+declare interface DocumentTranslationConfig {
+  /**
+   * Path to language field in documents. Can be a hidden field.
+   * For instance: 'config.language'
+   *
+   * For projects that use the `@sanity/document-internationalization` plugin,
+   * this should be the same as `languageField` config for that plugin.
+   *
+   * Default: 'language'
+   */
+  languageField: string
+  /**
+   * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+   *
+   * If defined, this property will add a translate instruction to these document types.
+   * If undefined, the instruction will be added to all documents with aiAssistance enabled and a field matching `documentLanguageField` config.
+   *
+   * Documents with translation support will get a "Translate document>" instruction added.
+   **/
+  documentTypes?: string[]
+}
+
+declare interface FieldTranslationConfig {
+  /**
+   * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+   *
+   * If defined, matching document will get a "Translate fields" instruction added.
+   **/
+  documentTypes?: string[]
+  /**
+   *
+   * Used for display strings in the Studio, and to determine languages for field level translations
+   *
+   * If the studio is using the sanity-plugin-internationalized-array plugin, this
+   * should be set to the same configuration.
+   */
+  languages: Language[] | LanguageCallback
+  /**
+   * API version for client passed to LanguageCallback for languages
+   * https://www.sanity.io/docs/api-versioning
+   * @defaultValue '2022-11-27'
+   */
+  apiVersion?: string
+  /**
+   * Specify fields that should be available in the languages callback:
+   * ```tsx
+   * {
+   *   select: {
+   *     markets: 'markets'
+   *   },
+   *   languages: (client, {markets}) =>
+   *     client.fetch('*[_type == "language" && market in $markets]{id,title}', {markets})
+   * }
+   * ```
+   *
+   * If the studio is using the sanity-plugin-internationalized-array plugin, this
+   * should be set to the same configuration.
+   */
+  selectLanguageParams?: Record<string, string>
+  /**
+     * `translationOutputs` is used when the "Translate fields" instruction is started by a Studio user.
+     *
+     *  It determines the relationships between document paths: Given a document path and a language, into which
+     *  sibling paths should translations be output.
+
+     *
+     * `translationOutputs` is invoked once per path in the document (limited to a depth of 6), with the following:
+     *
+     *  * `documentMember` - the field or array item for a given path; contains the path and its schemaType,
+     *  * `enclosingType` - the schema type of parent holding the member
+     *  * `translateFromLanguageId` - the languageId for the language the user want to translate from
+     *  * `translateToLanguageIds` - all languageIds the user can translate to
+     *
+     * The function should return a `TranslationOutput[]` array that contains all the paths where translations from
+     * documentMember language (translateFromLanguageId) should be output.
+     *
+     * The function should return `undefined` for all documentMembers that should not be directly translated,
+     * or are nested fields under a translated path.
+     *
+     * ## Default function
+     *
+     * The default function for `translationOutputs` is configured to be automatically compatible with sanity-plugin-internationalized-array
+     * and object types prefixed with "locale".
+     *
+     * See <link to source for defaultTranslationOutputs> implementation details.
+     *
+     * ## Example
+     * A document has the following document members:
+     * * `{path: 'localeObject.en', schemaType: ObjectSchemaType}`
+     * * `{path: 'localeObject.en.title', schemaType: StringSchemaType}`
+     * * `{path: 'localeObject.de', schemaType: ObjectSchemaType}`,
+     * * `{path: 'localeObject.de.title', schemaType: StringSchemaType}`
+     *
+     * `translationOutputs` for invoked with `translateFromLanguageId` `en`,
+     * should only return [{id: 'de', outputPath: 'localeObject.de'}] for the `'localeObject.en'` path,
+     * and undefined for all the other members.
+     *
+     * ### Example implementation
+     * ```ts
+     * function translationOutputs(member, enclosingType, translateFromLanguageId, translateToLanguageIds)
+     *   if (enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale') && translateFromLanguageId === member.name) {
+     *      return translateToLanguageIds.map((translateToId) => ({
+     *         id: translateToId,
+     *         outputPath: [...member.path.slice(0, -1), translateToId],
+     *      }))
+     *   }
+     *   return undefined
+     * }
+     * ```
+     **/
+  translationOutputs?: TranslationOutputsFunction
+}
+
+declare interface Language {
+  id: string
+  title?: string
+}
+
+declare type LanguageCallback = (
+  client: SanityClient,
+  selectedLanguageParams: Record<string, unknown>,
+) => Promise<Language[]>
+
 export declare function SchemaTypeTool(): JSX_2.Element
 
+declare interface TranslationConfig {
+  /**
+   * Config for document types with fields in multiple languages in the same document.
+   */
+  field?: FieldTranslationConfig
+  /**
+   * Config for document types with a single language field that determines the language for the whole document.
+   */
+  document?: DocumentTranslationConfig
+}
+
+declare interface TranslationOutput {
+  /** Language id */
+  id: string
+  outputPath: Path
+}
+
+declare type TranslationOutputsFunction = (
+  documentMember: DocumentMember,
+  enclosingType: SchemaType,
+  translateFromLanguageId: string,
+  translateToLanguageIds: string[],
+) => TranslationOutput[] | undefined
+
 export {}
 
 declare module 'sanity' {
@@ -44,7 +201,17 @@ declare module 'sanity' {
   }
   interface NumberOptions extends AssistOptions {}
   interface ObjectOptions extends AssistOptions {}
-  interface ReferenceBaseOptions extends AssistOptions {}
+  interface ReferenceBaseOptions {
+    aiWritingAssistance?: {
+      /** Set to true to disable assistance for this field or type */
+      exclude?: boolean
+      /**
+       * When set, the reference field will allow instructions to be added to it.
+       * Should be the name of the embeddings-index where assist will look for contextually relevant documents
+       * */
+      embeddingsIndex?: string
+    }
+  }
   interface SlugOptions extends AssistOptions {}
   interface StringOptions extends AssistOptions {}
   interface TextOptions extends AssistOptions {}