@sanity/client 7.0.1-canary.2 → 7.2.0

package/src/agent/actions/generate.ts

@@ -0,0 +1,274 @@
+import {type Observable} from 'rxjs'
+
+import {_request} from '../../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
+import type {AgentActionParams, Any, HttpRequest, IdentifiedSanityDocumentStub} from '../../types'
+import {hasDataset} from '../../validators'
+import type {
+  AgentActionAsync,
+  AgentActionPathSegment,
+  AgentActionRequestBase,
+  AgentActionSync,
+  AgentActionTarget,
+  AgentActionTargetInclude,
+} from './commonTypes'
+
+/**  @beta */
+export type GenerateOperation = 'set' | 'append' | 'mixed'
+
+/**  @beta */
+export interface GenerateRequestBase extends AgentActionRequestBase {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+  /**
+   * Instruct the LLM how it should generate content. Be as specific and detailed as needed.
+   *
+   * The LLM only has access to information in the instruction, plus the target schema.
+   *
+   * string template using $variable
+   * */
+  instruction: string
+  /**
+   * param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable"
+   *
+   * ### Examples
+   *
+   * #### Constant
+   *
+   * ##### Shorthand
+   * ```ts
+   * client.agent.action.generate({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following topic:\n $topic \n ---\nGenerate the full article.',
+   *   instructionParams: {
+   *     topic: 'Grapefruit'
+   *   },
+   * })
+   * ```
+   * ##### Object-form
+   *
+   * ```ts
+   * client.agent.action.generate({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following topic:\n $topic \n ---\nGenerate the full article.',
+   *   instructionParams: {
+   *     topic: {
+   *       type: 'constant',
+   *       value: 'Grapefruit'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Field
+   * ```ts
+   * client.agent.action.generate({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following field value:\n $pte \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     pte: {
+   *       type: 'field',
+   *       path: ['pteField'],
+   *     },
+   *   },
+   *   target: {path: 'keywords' }
+   * })
+   * ```
+   * #### Document
+   * ```ts
+   * client.agent.action.generate({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following document value:\n $document \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     document: {
+   *       type: 'document',
+   *     },
+   *   },
+   *   target: {path: 'keywords' }
+   * })
+   * ```
+   *
+   * #### GROQ
+   * ```ts
+   * client.agent.action.generate({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following list of titles:\n $list \n ---\nGenerate a similar title.',
+   *   instructionParams: {
+   *     list: {
+   *       type: 'groq',
+   *       query: '* [_type==$type].title',
+   *       params: {type: 'article'}
+   *     },
+   *   },
+   *   target: {path: 'title' }
+   * })
+   * ```
+   * */
+  instructionParams?: AgentActionParams
+
+  /**
+   * Target defines which parts of the document will be affected by the instruction.
+   * It can be an array, so multiple parts of the document can be separately configured in detail.
+   *
+   * Omitting target implies that the document itself is the root.
+   *
+   * Notes:
+   * - instruction can only affect fields up to `maxPathDepth`
+   * - when multiple targets are provided, they will be coalesced into a single target sharing a common target root.
+   * It is therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
+   *
+   * @see AgentActionRequestBase#conditionalPaths
+   */
+  target?: GenerateTarget | GenerateTarget[]
+}
+
+/**  @beta */
+export interface GenerateTargetInclude extends AgentActionTargetInclude {
+  /**
+   * Sets the operation for this path, and all its children.
+   * This overrides any operation set parents or the root target.
+   * @see #GenerateTarget.operation
+   * @see #include
+   */
+  operation?: GenerateOperation
+
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (AgentActionPathSegment | GenerateTargetInclude)[]
+}
+
+/**  @beta */
+export interface GenerateTarget extends AgentActionTarget {
+  /**
+   * Sets the default operation for all paths in the target.
+   * Generate runs in `'mixed'` operation mode by default:
+   * Changes are set in all non-array fields, and append to all array fields.
+   *
+   * ### Operation types
+   * - `'set'` – an *overwriting* operation, and replaces the full field value.
+   * - `'append'`:
+   *    – array fields: appends new items to the end of the array,
+   *    - string fields: '"existing content" "new content"'
+   *    - text fields: '"existing content"\\n"new content"'
+   *    - number fields: existing + new
+   *    - other field types not mentioned will set instead (dates, url)
+   * - `'mixed'` – (default) sets non-array fields, and appends to array fields
+   *
+   * The default operation can be overridden on a per-path basis using `include`.
+   *
+   * Nested fields inherit the operation specified by their parent and falls back to the
+   * top level target operation if not otherwise specified.
+   *
+   * Use `include` to change the `operation` of individual fields or items.
+   *
+   * #### Appending in the middle of arrays
+   * `target: {path: ['array'], operation: 'append'}` will append the output of the instruction to the end of the array.
+   *
+   * To insert in the middle of the array, use `target: {path: ['array', {_key: 'appendAfterKey'}], operation: 'append'}`.
+   * Here, the output of the instruction will be appended after the array item with key `'appendAfterKey'`.
+   *
+   * @see #AgentActionTargetInclude.operation
+   * @see #include
+   * @see #AgentActionTargetInclude.include
+   */
+  operation?: GenerateOperation
+
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (AgentActionPathSegment | GenerateTargetInclude)[]
+}
+
+/**  @beta */
+export type GenerateTargetDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | {
+      operation: 'edit'
+      _id: string
+    }
+  | {
+      operation: 'create'
+      _id?: string
+      _type: string
+      initialValues?: T
+    }
+  | {
+      operation: 'createIfNotExists'
+      _id: string
+      _type: string
+      initialValues?: T
+    }
+  | {
+      operation: 'createOrReplace'
+      _id: string
+      _type: string
+      initialValues?: T
+    }
+
+/**
+ * Instruction for an existing document.
+ * @beta
+ */
+interface GenerateExistingDocumentRequest {
+  documentId: string
+  createDocument?: never
+}
+
+/**
+ * Instruction to create a new document
+ * @beta
+ */
+interface GenerateTargetDocumentRequest<T extends Record<string, Any> = Record<string, Any>> {
+  targetDocument: GenerateTargetDocument<T>
+  documentId?: never
+}
+
+/** @beta */
+export type GenerateSyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
+  | GenerateExistingDocumentRequest
+  | GenerateTargetDocumentRequest<T>
+) &
+  GenerateRequestBase &
+  AgentActionSync
+
+/** @beta */
+export type GenerateAsyncInstruction<T extends Record<string, Any> = Record<string, Any>> = (
+  | GenerateExistingDocumentRequest
+  | GenerateTargetDocumentRequest<T>
+) &
+  GenerateRequestBase &
+  AgentActionAsync
+
+/** @beta */
+export type GenerateInstruction<T extends Record<string, Any> = Record<string, Any>> =
+  | GenerateSyncInstruction<T>
+  | GenerateAsyncInstruction<T>
+
+export function _generate<DocumentShape extends Record<string, Any>>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: GenerateInstruction<DocumentShape>,
+): Observable<
+  (typeof request)['async'] extends true
+    ? {_id: string}
+    : IdentifiedSanityDocumentStub & DocumentShape
+> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/agent/action/generate/${dataset}`,
+    body: request,
+  })
+}

package/src/agent/actions/transform.ts

@@ -0,0 +1,215 @@
+import {type Observable} from 'rxjs'
+
+import {_request} from '../../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
+import type {AgentActionParams, Any, HttpRequest, IdentifiedSanityDocumentStub} from '../../types'
+import {hasDataset} from '../../validators'
+import type {
+  AgentActionAsync,
+  AgentActionPathSegment,
+  AgentActionRequestBase,
+  AgentActionSync,
+  AgentActionTarget,
+  AgentActionTargetInclude,
+} from './commonTypes'
+
+/** @beta */
+export interface TransformRequestBase extends AgentActionRequestBase {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+
+  /**
+   * The source document the transformation will use as input.
+   */
+  documentId: string
+
+  /**
+   * The source document's content is first copied to the target,
+   * then it is transformed according to the instruction.
+   *
+   * When omitted, the source document (documentId) is also the target document.
+   */
+  targetDocument?: TransformTargetDocument
+
+  /**
+   * Instruct the LLM how to transform the input to th output.
+   *
+   * String template using $variable from instructionParams.
+   *
+   * Capped to 2000 characters, after variables has been injected.
+   * */
+  instruction: string
+  /**
+   *
+   * param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable"
+   *
+   * ### Examples
+   *
+   * #### Constant
+   *
+   * ##### Shorthand
+   * ```ts
+   * client.agent.action.generate({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following topic:\n $topic \n ---\nGenerate the full article.',
+   *   instructionParams: {
+   *     topic: 'Grapefruit'
+   *   },
+   * })
+   * ```
+   * ##### Object-form
+   *
+   * ```ts
+   * client.agent.action.transform({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following topic:\n $topic \n ---\nGenerate the full article.',
+   *   instructionParams: {
+   *     topic: {
+   *       type: 'constant',
+   *       value: 'Grapefruit'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Field
+   * ```ts
+   * client.agent.action.transform({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following field value:\n $pte \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     pte: {
+   *       type: 'field',
+   *       path: ['pteField'],
+   *     },
+   *   },
+   *   target: {path: 'keywords' }
+   * })
+   * ```
+   * #### Document
+   * ```ts
+   * client.agent.action.transform({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following document value:\n $document \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     document: {
+   *       type: 'document',
+   *     },
+   *   },
+   *   target: {path: 'keywords' }
+   * })
+   * ```
+   *
+   * #### GROQ
+   * ```ts
+   * client.agent.action.transform({
+   *   schemaId,
+   *   documentId,
+   *   instruction: 'Give the following list of titles:\n $list \n ---\nGenerate a similar title.',
+   *   instructionParams: {
+   *     list: {
+   *       type: 'groq',
+   *       query: '* [_type==$type].title',
+   *       params: {type: 'article'}
+   *     },
+   *   },
+   *   target: {path: 'title'}
+   * })
+   * ```
+   * */
+  instructionParams?: AgentActionParams
+
+  /**
+   * Target defines which parts of the document will be affected by the instruction.
+   * It can be an array, so multiple parts of the document can be separately configured in detail.
+   *
+   * Omitting target implies that the document itself is the root.
+   *
+   * Notes:
+   * - instruction can only affect fields up to `maxPathDepth`
+   * - when multiple targets are provided, they will be coalesced into a single target sharing a common target root.
+   * It is therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
+   *
+   * Default max depth for transform: 12
+   * @see AgentActionRequestBase#conditionalPaths
+   */
+  target?: TransformTarget | TransformTarget[]
+}
+
+/**  @beta */
+export type TransformTargetDocument =
+  | {operation: 'edit'; _id: string}
+  | {operation: 'create'; _id?: string}
+  | {operation: 'createIfNotExists'; _id: string}
+  | {operation: 'createOrReplace'; _id: string}
+
+/**  @beta */
+export interface TransformTargetInclude extends AgentActionTargetInclude {
+  /**
+   * Specifies a tailored instruction of this target.
+   *
+   * string template using $variable from instructionParams  */
+  instruction?: string
+
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (AgentActionPathSegment | TransformTargetInclude)[]
+}
+
+/**  @beta */
+export interface TransformTarget extends AgentActionTarget {
+  /**
+   * Specifies a tailored instruction of this target.
+   *
+   * string template using $variable from instructionParams.
+   * */
+  instruction?: string
+
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (AgentActionPathSegment | TransformTargetInclude)[]
+}
+
+/** @beta */
+// need the generics to hold optional call-site response generics
+// eslint-disable-next-line unused-imports/no-unused-vars
+export type TransformDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
+  TransformRequestBase & AgentActionSync
+
+/** @beta */
+export type TransformDocumentAsync = TransformRequestBase & AgentActionAsync
+
+/** @beta */
+export type TransformDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | TransformDocumentSync<T>
+  | TransformDocumentAsync
+
+export function _transform<DocumentShape extends Record<string, Any>>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: TransformDocument<DocumentShape>,
+): Observable<
+  (typeof request)['async'] extends true
+    ? {_id: string}
+    : IdentifiedSanityDocumentStub & DocumentShape
+> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/agent/action/transform/${dataset}`,
+    body: request,
+  })
+}

package/src/agent/actions/translate.ts

@@ -0,0 +1,165 @@
+import {type Observable} from 'rxjs'
+
+import {_request} from '../../data/dataMethods'
+import type {ObservableSanityClient, SanityClient} from '../../SanityClient'
+import type {
+  AgentActionParams,
+  AgentActionPathSegment,
+  AgentActionTarget,
+  Any,
+  HttpRequest,
+  IdentifiedSanityDocumentStub,
+} from '../../types'
+import {hasDataset} from '../../validators'
+import type {
+  AgentActionAsync,
+  AgentActionPath,
+  AgentActionRequestBase,
+  AgentActionSync,
+  AgentActionTargetInclude,
+} from './commonTypes'
+import type {TransformTargetDocument} from './transform'
+
+/**  @beta */
+export interface TranslateRequestBase extends AgentActionRequestBase {
+  /** schemaId as reported by sanity deploy / sanity schema store */
+  schemaId: string
+
+  /**
+   * The source document the transformation will use as input.
+   */
+  documentId: string
+
+  /**
+   * The target document will first get content copied over from the source,
+   * then it is translated according to the instruction.
+   *
+   * When omitted, the source document (documentId) is also the target document.
+   */
+  targetDocument?: TransformTargetDocument
+
+  /**
+   * While optional, it is recommended
+   */
+  fromLanguage?: TranslateLanguage
+  toLanguage: TranslateLanguage
+
+  /**
+   * `styleGuide` can be used to tailor how the translation should be preformed.
+   *
+   * String template using $variable from styleGuideParams.
+   *
+   * Capped to 2000 characters, after variables has been injected.
+   *
+   * @see #protectedPhrases
+   */
+  styleGuide?: string
+  /** param values for the string template, keys are the variable name, ie if the template has "$variable", one key must be "variable" */
+  styleGuideParams?: AgentActionParams
+
+  /**
+   * When the input string contains any phrase from `protectedPhrases`, the LLM will be instructed not
+   * to translate them.
+   *
+   * It is recommended to use `protectedPhrases` instead of `styleGuide` for deny-list words and phrases,
+   * since it keeps token cost low, resulting in faster responses, and limits how much information the LLM
+   * has to process, since only phrases that are actually in the input string will be included in the final prompt.
+   */
+  protectedPhrases?: string[]
+
+  /**
+   * When specified, the `toLanguage.id` will be stored in the specified path in the target document.
+   *
+   * The file _can_ be hidden: true (unlike other fields in the target, which will be ignored)
+   */
+  languageFieldPath?: AgentActionPathSegment | AgentActionPath
+
+  /**
+   * Target defines which parts of the document will be affected by the instruction.
+   * It can be an array, so multiple parts of the document can be separately configured in detail.
+   *
+   * Omitting target implies that the document itself is the root.
+   *
+   * Notes:
+   * - instruction can only affect fields up to `maxPathDepth`
+   * - when multiple targets are provided, they will be coalesced into a single target sharing a common target root.
+   * It is therefor an error to provide conflicting include/exclude across targets (ie, include title in one, and exclude it in another)
+   *
+   * @see AgentActionRequestBase#conditionalPaths
+   */
+  target?: TranslateTarget | TranslateTarget[]
+}
+
+/**  @beta */
+export interface TranslateLanguage {
+  /**
+   * Language code
+   */
+  id: string
+
+  /**
+   * While optional, it is recommended to provide a language title
+   */
+  title?: string
+}
+
+/**  @beta */
+export interface TranslateTargetInclude extends AgentActionTargetInclude {
+  /** string template using $variable from instructionParams  */
+  styleGuide?: string
+
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (AgentActionPathSegment | TranslateTargetInclude)[]
+}
+
+/**  @beta */
+export interface TranslateTarget extends AgentActionTarget {
+  /** string template using $variable from instructionParams  */
+  styleGuide?: string
+
+  /**
+   * By default, all children up to `target.maxPathDepth` are included.
+   *
+   * When `include` is specified, only segments explicitly listed will be included.
+   *
+   * Fields or array items not on the include list, are implicitly excluded.
+   */
+  include?: (AgentActionPathSegment | TranslateTargetInclude)[]
+}
+
+/** @beta */
+// need the generics to hold optional call-site response generics
+// eslint-disable-next-line unused-imports/no-unused-vars
+export type TranslateDocumentSync<T extends Record<string, Any> = Record<string, Any>> =
+  TranslateRequestBase & AgentActionSync
+
+/** @beta */
+export type TranslateDocumentAsync = TranslateRequestBase & AgentActionAsync
+
+/** @beta */
+export type TranslateDocument<T extends Record<string, Any> = Record<string, Any>> =
+  | TranslateDocumentSync<T>
+  | TranslateDocumentAsync
+
+export function _translate<DocumentShape extends Record<string, Any>>(
+  client: SanityClient | ObservableSanityClient,
+  httpRequest: HttpRequest,
+  request: TranslateDocument<DocumentShape>,
+): Observable<
+  (typeof request)['async'] extends true
+    ? {_id: string}
+    : IdentifiedSanityDocumentStub & DocumentShape
+> {
+  const dataset = hasDataset(client.config())
+  return _request(client, httpRequest, {
+    method: 'POST',
+    uri: `/agent/action/translate/${dataset}`,
+    body: request,
+  })
+}