@sanity/client 7.2.0 → 7.2.1-agent-actions.0

package/dist/index.browser.d.cts

@@ -55,15 +55,27 @@ declare interface AgentActionAsync {
 }
 
 /** @beta */
-export declare type AgentActionParam =
+export declare type AgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> =
   | string
   | ConstantAgentActionParam
-  | FieldAgentActionParam
-  | DocumentAgentActionParam
+  | FieldAgentActionParam<TParamConfig>
+  | DocumentAgentActionParam<TParamConfig>
   | GroqAgentActionParam
 
 /** @beta */
-export declare type AgentActionParams = Record<string, AgentActionParam>
+export declare type AgentActionParams<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = Record<string, AgentActionParam<TParamConfig>>
 
 /**  @beta */
 export declare type AgentActionPath = AgentActionPathSegment[]
@@ -192,6 +204,13 @@ declare class AgentActionsClient {
         }
       : IdentifiedSanityDocumentStub & DocumentShape
   >
+  /**
+   * Run a raw instruction and return the result either as text or json
+   * @param request - prompt request
+   */
+  prompt<DocumentShape extends Record<string, Any>>(
+    request: PromptRequest<DocumentShape>,
+  ): Promise<(typeof request)['json'] extends true ? DocumentShape : string>
 }
 
 /** @beta */
@@ -1095,6 +1114,23 @@ export declare type DisconnectEvent = {
   reason: string
 }
 
+declare type DocIdParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = TParamConfig['docIdRequired'] extends true
+  ? {
+      documentId: string
+    }
+  : {
+      /**
+       * If omitted, implicitly uses the documentId of the instruction target
+       */
+      documentId?: string
+    }
+
 /**
  *
  * Includes a LLM-friendly version of the document in the instruction
@@ -1115,13 +1151,15 @@ export declare type DisconnectEvent = {
  *
  * @beta
  * */
-export declare interface DocumentAgentActionParam {
+export declare type DocumentAgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = {
   type: 'document'
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /** @internal */
 export declare type EditableReleaseDocument = Omit<
@@ -1208,17 +1246,19 @@ export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSo
  *
  * @beta
  * */
-export declare interface FieldAgentActionParam {
+export declare type FieldAgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = {
   type: 'field'
   /**
    * Examples: 'title', ['array', \{_key: 'arrayItemKey'\}, 'field']
    */
   path: AgentActionPathSegment | AgentActionPath
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /** @public */
 export declare type FilterDefault = (props: {
@@ -3429,6 +3469,136 @@ export declare class ProjectsClient {
   getById(projectId: string): Promise<SanityProject>
 }
 
+/**
+ * @beta
+ */
+declare interface PromptJsonResponse<T extends Record<string, Any> = Record<string, Any>> {
+  /**
+   *
+   * When true, the response body will be json according to the instruction.
+   * When false, the response is the raw text response to the instruction.
+   *
+   * Note: In addition to setting this to true,  `instruction` MUST include the word 'JSON', or 'json' for this to work.
+   */
+  json: true
+}
+
+/** @beta */
+export declare type PromptRequest<T extends Record<string, Any> = Record<string, Any>> = (
+  | PromptTextResponse
+  | PromptJsonResponse<T>
+) &
+  PromptRequestBase
+
+/**  @beta */
+declare interface PromptRequestBase {
+  /**
+   * 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 ---\nReturns some facts about it',
+   *   instructionParams: {
+   *     topic: 'Grapefruit'
+   *   },
+   * })
+   * ```
+   * ##### Object-form
+   *
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following topic:\n $topic \n ---\nReturns some facts about it.',
+   *   instructionParams: {
+   *     topic: {
+   *       type: 'constant',
+   *       value: 'Grapefruit'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Field
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following field value:\n $pte \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     pte: {
+   *       type: 'field',
+   *       path: ['pteField'],
+   *       documentId: 'someSanityDocId'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Document
+   * ```ts
+   * client.agent.action.prompt({
+   *   json: true,
+   *   instruction: 'Given the following document:$document\nCreate a JSON string[] array with keywords describing it.',
+   *   instructionParams: {
+   *     document: {
+   *       type: 'document',
+   *       documentId: 'someSanityDocId'
+   *     },
+   *   },
+   * })
+   * ```
+   *
+   * #### GROQ
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Return the best title amongst these: $titles.',
+   *   instructionParams: {
+   *     titles: {
+   *       type: 'groq',
+   *       query: '* [_type==$type].title',
+   *       params: {type: 'article'}
+   *     },
+   *   },
+   * })
+   * ```
+   * */
+  instructionParams?: AgentActionParams<{
+    docIdRequired: true
+  }>
+  /**
+   * Controls how much variance the instructions will run with.
+   *
+   * Value must be in the range [0, 1] (inclusive).
+   *
+   * Defaults:
+   * - generate: 0.3
+   * - translate: 0
+   * - transform: 0
+   */
+  temperature?: number
+}
+
+declare interface PromptTextResponse {
+  /**
+   *
+   * When true, the response body will be json according to the instruction.
+   * When false, the response is the raw text response to the instruction.
+   *
+   * Note: In addition to setting this to true,  `instruction` MUST include the word 'JSON', or 'json' for this to work.
+   */
+  json?: false
+}
+
 /**
  * Publishes a draft document.
  * If a published version of the document already exists this is replaced by the current draft document.

package/dist/index.browser.d.ts

@@ -55,15 +55,27 @@ declare interface AgentActionAsync {
 }
 
 /** @beta */
-export declare type AgentActionParam =
+export declare type AgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> =
   | string
   | ConstantAgentActionParam
-  | FieldAgentActionParam
-  | DocumentAgentActionParam
+  | FieldAgentActionParam<TParamConfig>
+  | DocumentAgentActionParam<TParamConfig>
   | GroqAgentActionParam
 
 /** @beta */
-export declare type AgentActionParams = Record<string, AgentActionParam>
+export declare type AgentActionParams<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = Record<string, AgentActionParam<TParamConfig>>
 
 /**  @beta */
 export declare type AgentActionPath = AgentActionPathSegment[]
@@ -192,6 +204,13 @@ declare class AgentActionsClient {
         }
       : IdentifiedSanityDocumentStub & DocumentShape
   >
+  /**
+   * Run a raw instruction and return the result either as text or json
+   * @param request - prompt request
+   */
+  prompt<DocumentShape extends Record<string, Any>>(
+    request: PromptRequest<DocumentShape>,
+  ): Promise<(typeof request)['json'] extends true ? DocumentShape : string>
 }
 
 /** @beta */
@@ -1095,6 +1114,23 @@ export declare type DisconnectEvent = {
   reason: string
 }
 
+declare type DocIdParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = TParamConfig['docIdRequired'] extends true
+  ? {
+      documentId: string
+    }
+  : {
+      /**
+       * If omitted, implicitly uses the documentId of the instruction target
+       */
+      documentId?: string
+    }
+
 /**
  *
  * Includes a LLM-friendly version of the document in the instruction
@@ -1115,13 +1151,15 @@ export declare type DisconnectEvent = {
  *
  * @beta
  * */
-export declare interface DocumentAgentActionParam {
+export declare type DocumentAgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = {
   type: 'document'
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /** @internal */
 export declare type EditableReleaseDocument = Omit<
@@ -1208,17 +1246,19 @@ export declare type EventSourceInstance = InstanceType<typeof globalThis.EventSo
  *
  * @beta
  * */
-export declare interface FieldAgentActionParam {
+export declare type FieldAgentActionParam<
+  TParamConfig extends {
+    docIdRequired: boolean
+  } = {
+    docIdRequired: false
+  },
+> = {
   type: 'field'
   /**
    * Examples: 'title', ['array', \{_key: 'arrayItemKey'\}, 'field']
    */
   path: AgentActionPathSegment | AgentActionPath
-  /**
-   * If omitted, implicitly uses the documentId of the instruction target
-   */
-  documentId?: string
-}
+} & DocIdParam<TParamConfig>
 
 /** @public */
 export declare type FilterDefault = (props: {
@@ -3429,6 +3469,136 @@ export declare class ProjectsClient {
   getById(projectId: string): Promise<SanityProject>
 }
 
+/**
+ * @beta
+ */
+declare interface PromptJsonResponse<T extends Record<string, Any> = Record<string, Any>> {
+  /**
+   *
+   * When true, the response body will be json according to the instruction.
+   * When false, the response is the raw text response to the instruction.
+   *
+   * Note: In addition to setting this to true,  `instruction` MUST include the word 'JSON', or 'json' for this to work.
+   */
+  json: true
+}
+
+/** @beta */
+export declare type PromptRequest<T extends Record<string, Any> = Record<string, Any>> = (
+  | PromptTextResponse
+  | PromptJsonResponse<T>
+) &
+  PromptRequestBase
+
+/**  @beta */
+declare interface PromptRequestBase {
+  /**
+   * 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 ---\nReturns some facts about it',
+   *   instructionParams: {
+   *     topic: 'Grapefruit'
+   *   },
+   * })
+   * ```
+   * ##### Object-form
+   *
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following topic:\n $topic \n ---\nReturns some facts about it.',
+   *   instructionParams: {
+   *     topic: {
+   *       type: 'constant',
+   *       value: 'Grapefruit'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Field
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Give the following field value:\n $pte \n ---\nGenerate keywords.',
+   *   instructionParams: {
+   *     pte: {
+   *       type: 'field',
+   *       path: ['pteField'],
+   *       documentId: 'someSanityDocId'
+   *     },
+   *   },
+   * })
+   * ```
+   * #### Document
+   * ```ts
+   * client.agent.action.prompt({
+   *   json: true,
+   *   instruction: 'Given the following document:$document\nCreate a JSON string[] array with keywords describing it.',
+   *   instructionParams: {
+   *     document: {
+   *       type: 'document',
+   *       documentId: 'someSanityDocId'
+   *     },
+   *   },
+   * })
+   * ```
+   *
+   * #### GROQ
+   * ```ts
+   * client.agent.action.prompt({
+   *   instruction: 'Return the best title amongst these: $titles.',
+   *   instructionParams: {
+   *     titles: {
+   *       type: 'groq',
+   *       query: '* [_type==$type].title',
+   *       params: {type: 'article'}
+   *     },
+   *   },
+   * })
+   * ```
+   * */
+  instructionParams?: AgentActionParams<{
+    docIdRequired: true
+  }>
+  /**
+   * Controls how much variance the instructions will run with.
+   *
+   * Value must be in the range [0, 1] (inclusive).
+   *
+   * Defaults:
+   * - generate: 0.3
+   * - translate: 0
+   * - transform: 0
+   */
+  temperature?: number
+}
+
+declare interface PromptTextResponse {
+  /**
+   *
+   * When true, the response body will be json according to the instruction.
+   * When false, the response is the raw text response to the instruction.
+   *
+   * Note: In addition to setting this to true,  `instruction` MUST include the word 'JSON', or 'json' for this to work.
+   */
+  json?: false
+}
+
 /**
  * Publishes a draft document.
  * If a published version of the document already exists this is replaced by the current draft document.

package/dist/index.browser.js

@@ -1042,6 +1042,14 @@ function _generate(client, httpRequest, request) {
     body: request
   });
 }
+function _prompt(client, httpRequest, request) {
+  const dataset2 = hasDataset(client.config());
+  return _request(client, httpRequest, {
+    method: "POST",
+    uri: `/agent/action/prompt/${dataset2}`,
+    body: request
+  });
+}
 function _transform(client, httpRequest, request) {
   const dataset2 = hasDataset(client.config());
   return _request(client, httpRequest, {
@@ -1113,6 +1121,13 @@ class AgentActionsClient {
   translate(request) {
     return lastValueFrom(_translate(this.#client, this.#httpRequest, request));
   }
+  /**
+   * Run a raw instruction and return the result either as text or json
+   * @param request - prompt request
+   */
+  prompt(request) {
+    return lastValueFrom(_prompt(this.#client, this.#httpRequest, request));
+  }
 }
 class ObservableAssetsClient {
   #client;