@sanity/assist 4.0.2 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/assist",
-  "version": "4.0.2",
+  "version": "4.2.0",
   "description": "You create the instructions; Sanity AI Assist does the rest.",
   "keywords": [
     "sanity",

package/src/components/ImageContext.tsx

@@ -40,7 +40,7 @@ export function ImageContextProvider(props: InputProps) {
     if (
       assetRef &&
       assistableDocumentId &&
-      descriptionField &&
+      descriptionField?.updateOnImageChange &&
       assetRef !== assetRefState &&
       !isSyncing &&
       !isShowingOlderRevision &&
@@ -49,7 +49,7 @@ export function ImageContextProvider(props: InputProps) {
       setAssetRefState(assetRef)
       if (canUseAssist(status)) {
         generateCaption({
-          path: pathToString([...path, descriptionField]),
+          path: pathToString([...path, descriptionField.path]),
           documentId: assistableDocumentId,
         })
       }
@@ -71,8 +71,8 @@ export function ImageContextProvider(props: InputProps) {
     const descriptionField = getDescriptionFieldOption(schemaType)
     const imageInstructionField = getImageInstructionFieldOption(schemaType)
     return {
-      imageDescriptionPath: descriptionField
-        ? pathToString([...path, descriptionField])
+      imageDescriptionPath: descriptionField?.path
+        ? pathToString([...path, descriptionField.path])
         : undefined,
       imageInstructionPath: imageInstructionField
         ? pathToString([...path, imageInstructionField])

package/src/helpers/styleguide.ts

@@ -0,0 +1,24 @@
+import {packageName} from '../constants'
+import {TranslateStyleguide, TranslateStyleguideContext} from '../translate/types'
+
+export function validateStyleguide(styleguide: string | undefined) {
+  if (styleguide && styleguide.length > 2000) {
+    throw new Error(
+      `[${packageName}]: \`translate.styleguide\` value is too long. It must be 2000 characters or less, but was ${styleguide.length} characters`,
+    )
+  }
+  return styleguide
+}
+
+export function createStyleGuideResolver(
+  styleguide: TranslateStyleguide | undefined,
+  context: TranslateStyleguideContext,
+) {
+  return async () => {
+    if (typeof styleguide !== 'function') {
+      return styleguide
+    }
+    const styleguideResult = await styleguide(context)
+    return validateStyleguide(styleguideResult)
+  }
+}

package/src/helpers/typeUtils.ts

@@ -18,13 +18,23 @@ export function isImage(schemaType: SchemaType) {
   return isType(schemaType, 'image')
 }
 
-export function getDescriptionFieldOption(schemaType: SchemaType | undefined): string | undefined {
+export function getDescriptionFieldOption(
+  schemaType: SchemaType | undefined,
+): {path: string; updateOnImageChange: boolean} | undefined {
   if (!schemaType) {
     return undefined
   }
   const descriptionField = (schemaType.options as ImageOptions)?.aiAssist?.imageDescriptionField
-  if (descriptionField) {
-    return descriptionField
+  if (typeof descriptionField === 'string') {
+    return {
+      path: descriptionField,
+      updateOnImageChange: true,
+    }
+  } else if (descriptionField) {
+    return {
+      path: descriptionField.path,
+      updateOnImageChange: descriptionField.updateOnImageChange ?? true,
+    }
   }
   return getDescriptionFieldOption(schemaType.type)
 }

package/src/plugin.tsx

@@ -9,17 +9,18 @@ import {AssistInlineFormBlock} from './assistFormComponents/AssistInlineFormBloc
 import {AssistItem} from './assistFormComponents/AssistItem'
 import {assistInspector} from './assistInspector'
 import {AssistLayout} from './assistLayout/AssistLayout'
+import {AssistConfig} from './assistTypes'
 import {ImageContextProvider} from './components/ImageContext'
 import {SafeValueInput} from './components/SafeValueInput'
 import {packageName} from './constants'
 import {assistFieldActions} from './fieldActions/assistFieldActions'
 import {isSchemaAssistEnabled} from './helpers/assistSupported'
+import {validateStyleguide} from './helpers/styleguide'
 import {isImage} from './helpers/typeUtils'
 import {createAssistDocumentPresence} from './presence/AssistDocumentPresence'
 import {schemaTypes} from './schemas'
 import {TranslationConfig} from './translate/types'
 import {assistDocumentTypeName, AssistPreset} from './types'
-import {AssistConfig} from './assistTypes'
 
 export interface AssistPluginConfig {
   translate?: TranslationConfig
@@ -46,10 +47,8 @@ export const assist = definePlugin<AssistPluginConfig | void>((config) => {
   const maxPathDepth = configWithDefaults.assist?.maxPathDepth
   const temperature = configWithDefaults.assist?.temperature
 
-  if (styleguide.length > 2000) {
-    throw new Error(
-      `[${packageName}]: \`translate.styleguide\` value is too long. It must be 2000 characters or less, was ${styleguide.length} characters`,
-    )
+  if (typeof styleguide === 'string') {
+    validateStyleguide(styleguide)
   }
 
   if (maxPathDepth !== undefined && (maxPathDepth < 1 || maxPathDepth > 12)) {

package/src/schemas/typeDefExtensions.ts

@@ -90,7 +90,18 @@ declare module 'sanity' {
        * })
        * ```
        */
-      imageDescriptionField?: string
+      imageDescriptionField?:
+        | string
+        | {
+            path: string
+            /**
+             * When updateOnImageChange is true (or undefined), whenever the
+             * image asset changes, imageDescriptionField will be regenerated.
+             *
+             * default:  true
+             * */
+            updateOnImageChange?: boolean
+          }
     }
   }
   interface NumberOptions extends AssistOptions {}

package/src/translate/FieldTranslationProvider.tsx

@@ -19,7 +19,8 @@ import {
 
 import {useAiAssistanceConfig} from '../assistLayout/AiAssistanceConfigContext'
 import type {ConditionalMemberState} from '../helpers/conditionalMembers'
-import {useApiClient, useTranslate} from '../useApiClient'
+import {createStyleGuideResolver} from '../helpers/styleguide'
+import {API_VERSION_WITH_EXTENDED_TYPES, useApiClient, useTranslate} from '../useApiClient'
 import {getLanguageParams} from './getLanguageParams'
 import {getPreferredToFieldLanguages, setPreferredToFieldLanguages} from './languageStore'
 import {
@@ -67,6 +68,7 @@ function hasValuesToTranslate(
 // eslint-disable-next-line @typescript-eslint/ban-types
 export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
   const {config: assistConfig} = useAiAssistanceConfig()
+
   const apiClient = useApiClient(assistConfig.__customApiClient)
   const styleguide = assistConfig.translate?.styleguide
   const config = assistConfig.translate?.field
@@ -87,7 +89,9 @@ export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
     setLanguages(undefined)
     setFieldTranslationParams(undefined)
   }, [])
-  const languageClient = useClient({apiVersion: config?.apiVersion ?? '2022-11-27'})
+  const languageClient = useClient({
+    apiVersion: config?.apiVersion ?? API_VERSION_WITH_EXTENDED_TYPES,
+  })
   const documentId = fieldTranslationParams?.document?._id
   const id = useId()
 
@@ -195,7 +199,12 @@ export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
       runTranslate({
         documentId,
         translatePath,
-        styleguide,
+        styleguide: createStyleGuideResolver(styleguide, {
+          client: languageClient,
+          documentId,
+          schemaType: fieldTranslationParams?.documentSchema,
+          translatePath,
+        }),
         fieldLanguageMap: fieldLanguageMaps.map((map) => ({
           ...map,
           // eslint-disable-next-line max-nested-callbacks
@@ -214,6 +223,8 @@ export function FieldTranslationProvider(props: PropsWithChildren<{}>) {
     toLanguages,
     fieldTranslationParams?.translatePath,
     fieldTranslationParams?.conditionalMembers,
+    fieldTranslationParams?.documentSchema,
+    languageClient,
   ])
 
   const runButton = (

package/src/translate/translateActions.tsx

@@ -2,12 +2,13 @@
 import {TranslateIcon} from '@sanity/icons'
 import {Box, Spinner} from '@sanity/ui'
 import {useMemo, useRef} from 'react'
-import type {
+import {
   DocumentFieldAction,
   DocumentFieldActionGroup,
   DocumentFieldActionItem,
   DocumentFieldActionProps,
   ObjectSchemaType,
+  useClient,
 } from 'sanity'
 import {useDocumentPane} from 'sanity/structure'
 
@@ -15,8 +16,9 @@ import {useDraftDelayedTask} from '../assistDocument/RequestRunInstructionProvid
 import {useAiAssistanceConfig} from '../assistLayout/AiAssistanceConfigContext'
 import {isAssistSupported} from '../helpers/assistSupported'
 import {getConditionalMembers} from '../helpers/conditionalMembers'
+import {createStyleGuideResolver} from '../helpers/styleguide'
 import type {AssistOptions} from '../schemas/typeDefExtensions'
-import {useApiClient, useTranslate} from '../useApiClient'
+import {API_VERSION_WITH_EXTENDED_TYPES, useApiClient, useTranslate} from '../useApiClient'
 import {useFieldTranslation} from './FieldTranslationProvider'
 
 function node(node: DocumentFieldActionItem | DocumentFieldActionGroup) {
@@ -32,7 +34,7 @@ export const translateActions: DocumentFieldAction = {
   useAction(props: TranslateProps) {
     const {config, status} = useAiAssistanceConfig()
     const apiClient = useApiClient(config?.__customApiClient)
-
+    const client = useClient({apiVersion: API_VERSION_WITH_EXTENDED_TYPES})
     const {
       schemaType: fieldSchemaType,
       path,
@@ -99,7 +101,11 @@ export const translateActions: DocumentFieldAction = {
             translate({
               languagePath,
               translatePath: path,
-              styleguide,
+              styleguide: createStyleGuideResolver(styleguide, {
+                client,
+                documentId,
+                schemaType: documentSchemaType,
+              }),
               documentId: documentId ?? '',
               conditionalMembers: formStateRef.current
                 ? getConditionalMembers(formStateRef.current)
@@ -118,6 +124,8 @@ export const translateActions: DocumentFieldAction = {
         documentTranslationEnabled,
         path,
         readOnly,
+        client,
+        documentSchemaType,
       ])
       const fieldTranslate = useFieldTranslation()
       const openFieldTranslation = useDraftDelayedTask({

package/src/translate/types.ts

@@ -1,4 +1,4 @@
-import {Path, SanityClient, SchemaType} from 'sanity'
+import {ObjectSchemaType, Path, SanityClient, SchemaType} from 'sanity'
 
 export interface Language {
   id: string
@@ -163,6 +163,20 @@ export interface DocumentTranslationConfig {
   documentTypes?: string[]
 }
 
+export interface TranslateStyleguideContext {
+  documentId: string
+  schemaType: ObjectSchemaType
+  client: SanityClient
+  /**
+   * Only provided for field translations
+   */
+  translatePath?: Path
+}
+
+export type TranslateStyleguide =
+  | string
+  | ((context: TranslateStyleguideContext) => Promise<string>)
+
 export interface TranslationConfig {
   /**
    * Config for document types with fields in multiple languages in the same document.
@@ -176,6 +190,8 @@ export interface TranslationConfig {
    * A "style guide" that can be used to provide guidance on how to translate content.
    * Will be passed to the LLM - ergo this is only a guide and the model _may_ not
    * always follow it to the letter.
+   *
+   * When providing a function, consider caching the results of any async operation; it will invoked every time translate runs
    */
-  styleguide?: string
+  styleguide?: TranslateStyleguide
 }

package/src/useApiClient.ts

@@ -35,13 +35,13 @@ export interface TranslateRequest {
   documentId: string
   translatePath: Path
   languagePath?: string
-  styleguide?: string
+  styleguide: () => Promise<string | undefined>
   fieldLanguageMap?: FieldLanguageMap[]
   conditionalMembers?: ConditionalMemberState[]
 }
 
 const basePath = '/assist/tasks/instruction'
-const API_VERSION_WITH_EXTENDED_TYPES = '2025-04-01'
+export const API_VERSION_WITH_EXTENDED_TYPES = '2025-04-01'
 
 export function canUseAssist(status: InstructStatus | undefined) {
   return status?.enabled && status.initialized && status.validToken
@@ -73,8 +73,8 @@ export function useTranslate(apiClient: SanityClient) {
     }: TranslateRequest) => {
       setLoading(true)
 
-      return apiClient
-        .request({
+      async function run() {
+        return apiClient.request({
           method: 'POST',
           url: `/assist/tasks/translate/${apiClient.config().dataset}?projectId=${
             apiClient.config().projectId
@@ -83,7 +83,7 @@ export function useTranslate(apiClient: SanityClient) {
             documentId,
             types,
             languagePath,
-            userStyleguide: styleguide,
+            userStyleguide: await styleguide(),
             fieldLanguageMap,
             conditionalMembers,
             translatePath:
@@ -91,6 +91,9 @@ export function useTranslate(apiClient: SanityClient) {
             userId: user?.id,
           },
         })
+      }
+
+      return run()
         .catch((e) => {
           toast.push({
             status: 'error',