@adobe/spacecat-shared-gpt-client 1.2.22 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-gpt-client-v1.3.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-gpt-client-v1.3.0...@adobe/spacecat-shared-gpt-client-v1.3.1) (2024-11-15)
+
+
+### Bug Fixes
+
+* SITES-26948 [Import Assistant] Allow calls to Firefall to use specified ims org id ([#443](https://github.com/adobe/spacecat-shared/issues/443)) ([a63016c](https://github.com/adobe/spacecat-shared/commit/a63016c426ae8a4c0f7f66653e49f1098d466ee8))
+
+# [@adobe/spacecat-shared-gpt-client-v1.3.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-gpt-client-v1.2.22...@adobe/spacecat-shared-gpt-client-v1.3.0) (2024-11-12)
+
+
+### Features
+
+* SITES-26591 [Import Assistant] Expand GPT client to user chat endpoint ([#436](https://github.com/adobe/spacecat-shared/issues/436)) ([4aaca2e](https://github.com/adobe/spacecat-shared/commit/4aaca2ede0fb9b019c8c88c2f7afd396065088b1))
+
 # [@adobe/spacecat-shared-gpt-client-v1.2.22](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-gpt-client-v1.2.21...@adobe/spacecat-shared-gpt-client-v1.2.22) (2024-11-11)
 
 

package/README.md

@@ -10,6 +10,11 @@ To use the `FirefallClient`, you need to configure it with the following paramet
 - `FIREFALL_API_KEY`: Your API key for accessing the Firefall API.
 - `FIREFALL_API_CAPABILITY_NAME`: The capability name for the Firefall API.
 
+Optionally, you can specify the IMS ORG ID to use when calling the Firefall APIs.  If this value is not specified, the IMS_CLIENT_ID (see below) will
+be used for the header's value:
+
+- `FIREFALL_IMS_ORG_ID`: The IMS ORG ID to use when calling the Firefall APIs and tracking the request.
+
 These parameters can be set through environment variables or passed directly to the `FirefallClient.createFrom` method.
 
 Additionally, the configuration for the `@adobe/spacecat-shared-ims-client` library is required to fetch the service access token from the IMS API:
@@ -42,7 +47,12 @@ try {
 
 ### Fetching Insights
 
+#### Via Capability Execution endpoint
+
 ```javascript
+/**
+ *  Fetch insights using the Firefall's capability execution endpoint.
+ */
 async function fetchInsights(prompt) {
   try {
     const client = FirefallClient.createFrom({
@@ -58,7 +68,7 @@ async function fetchInsights(prompt) {
       log: console,
     });
 
-    const insights = await client.fetch(prompt);
+    const insights = await client.fetchCapabilityExecution(prompt);
     console.log('Insights:', insights);
   } catch (error) {
     console.error('Failed to fetch insights:', error.message);
@@ -68,6 +78,41 @@ async function fetchInsights(prompt) {
 fetchInsights('How can we improve customer satisfaction?');
 ```
 
+#### Via Chat Completions endpoint
+
+```javascript
+/**
+ *  Fetch completions using the Firefall's chat completions endpoint.
+ */
+async function fetchCompletions(prompt) {
+  try {
+    const client = FirefallClient.createFrom({
+      env: {
+        FIREFALL_API_ENDPOINT: 'https://api.firefall.example.com',
+        FIREFALL_API_KEY: 'yourApiKey',
+        IMS_HOST: 'ims.example.com',
+        IMS_CLIENT_ID: 'yourClientId',
+        IMS_CLIENT_CODE: 'yourClientCode',
+        IMS_CLIENT_SECRET: 'yourClientSecret',
+      },
+      log: console,
+    });
+    const options = {
+      imageUrls: ['data:image/png;base64,iVBORw0KGgoAAAA...='],
+      model:'gpt-4-vision',
+      responseFormat: undefined,
+    };
+
+    const response = await client.fetchChatCompletion(prompt, { options });
+    console.log('Response:', JSON.stringify(response));
+  } catch (error) {
+    console.error('Failed to fetch chat completion:', error.message);
+  }
+}
+
+fetchCompletions('Identify all food items in this image', { imageUrls: ['data:image/png;base64,iVBORw0KGgoAAAA...='] });
+```
+
 Ensure that you replace `'path/to/firefall-client'` with the actual path to the `FirefallClient` class in your project and adjust the configuration parameters according to your Firefall API credentials.
 
 ## Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-gpt-client",
-  "version": "1.2.22",
+  "version": "1.3.1",
   "description": "Shared modules of the Spacecat Services - GPT Client",
   "type": "module",
   "engines": {

package/src/clients/firefall-client.js

@@ -16,7 +16,14 @@ import { hasText, isObject, isValidUrl } from '@adobe/spacecat-shared-utils';
 
 import { fetch as httpFetch } from '../utils.js';
 
-function validateFirefallResponse(response) {
+const USER_ROLE_IMAGE_URL_TYPE = 'image_url';
+const USER_ROLE_TEXT_TYPE = 'text';
+const SYSTEM_ROLE = 'system';
+const USER_ROLE = 'user';
+const AZURE_CHAT_OPENAI_LLM_TYPE = 'azure_chat_openai';
+const JSON_OBJECT_RESPONSE_FORMAT = 'json_object';
+
+function validateCapabilityExecutionResponse(response) {
   return !(!isObject(response)
     || !Array.isArray(response.generations)
     || response.generations.length === 0
@@ -25,6 +32,17 @@ function validateFirefallResponse(response) {
     || !hasText(response.generations[0][0].text));
 }
 
+function validateChatCompletionResponse(response) {
+  return isObject(response)
+    && Array.isArray(response?.choices)
+    && response.choices.length > 0
+    && response.choices[0]?.message;
+}
+
+function isBase64UrlImage(base64String) {
+  return base64String.startsWith('data:image') && base64String.endsWith('=') && base64String.includes('base64');
+}
+
 export default class FirefallClient {
   static createFrom(context) {
     const { log = console } = context;
@@ -32,7 +50,8 @@ export default class FirefallClient {
 
     const {
       FIREFALL_API_ENDPOINT: apiEndpoint,
-      IMS_CLIENT_ID: imsOrg,
+      IMS_CLIENT_ID: imsClientId,
+      FIREFALL_IMS_ORG_ID: firefallImsOrgId,
       FIREFALL_API_KEY: apiKey,
       FIREFALL_API_POLL_INTERVAL: pollInterval = 2000,
       FIREFALL_API_CAPABILITY_NAME: capabilityName = 'gpt4_32k_completions_capability',
@@ -51,7 +70,7 @@ export default class FirefallClient {
       apiKey,
       capabilityName,
       imsClient,
-      imsOrg,
+      imsOrg: firefallImsOrgId || imsClientId,
       pollInterval,
     }, log);
   }
@@ -89,15 +108,16 @@ export default class FirefallClient {
     this.log.debug(`${message}: took ${duration}ms`);
   }
 
-  async #submitJob(prompt) {
+  /**
+   * Submit a prompt to the Firefall API.
+   * @param body The body of the request.
+   * @param path The Firefall API path.
+   * @returns {Promise<unknown>}
+   */
+  async #submitPrompt(body, path) {
     const apiAuth = await this.#getApiAuth();
 
-    const body = JSON.stringify({
-      input: prompt,
-      capability_name: this.config.capabilityName,
-    });
-
-    const url = createUrl(`${this.config.apiEndpoint}/v2/capability_execution/job`);
+    const url = createUrl(`${this.config.apiEndpoint}${path}`);
     const headers = {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${apiAuth}`,
@@ -121,7 +141,7 @@ export default class FirefallClient {
   }
 
   /* eslint-disable no-await-in-loop */
-  async #pollJobStatus(jobId) {
+  async #pollJobStatus(jobId, path) {
     const apiAuth = await this.#getApiAuth();
 
     let jobStatusResponse;
@@ -130,7 +150,7 @@ export default class FirefallClient {
         (resolve) => { setTimeout(resolve, this.config.pollInterval); },
       ); // Wait for 2 seconds before polling
 
-      const url = `${this.config.apiEndpoint}/v2/capability_execution/job/${jobId}`;
+      const url = `${this.config.apiEndpoint}${path}/${jobId}`;
       const headers = {
         Authorization: `Bearer ${apiAuth}`,
         'x-api-key': this.config.apiKey,
@@ -161,23 +181,131 @@ export default class FirefallClient {
     return jobStatusResponse;
   }
 
-  async fetch(prompt) {
+  /**
+   * Fetches data from Firefall Chat Completion API.
+   * @param prompt The text prompt to provide to Firefall
+   * @param options The options for the call, with optional properties:
+   *          - imageUrls: An array of URLs of the images to provide to Firefall
+   *          - model: LLM Model to use (default: gpt-4-turbo).  Use 'gpt-4-vision' with images.
+   *          - responseFormat: The response format to request from Firefall (accepts: json_object)
+   * @returns {Object} - AI response
+   */
+  async fetchChatCompletion(prompt, options = {}) {
+    const {
+      imageUrls,
+      responseFormat,
+      model: llmModel = 'gpt-4-turbo',
+    } = options || {};
+    const hasImageUrls = imageUrls && imageUrls.length > 0;
+
+    const getBody = () => {
+      const userRole = {
+        role: USER_ROLE,
+        content: [
+          {
+            type: USER_ROLE_TEXT_TYPE,
+            text: prompt,
+          },
+        ],
+      };
+
+      if (hasImageUrls) {
+        imageUrls
+          .filter((iu) => isValidUrl(iu) || isBase64UrlImage(iu))
+          .forEach((imageUrl) => {
+            userRole.content.push({
+              type: USER_ROLE_IMAGE_URL_TYPE,
+              image_url: {
+                url: imageUrl,
+              },
+            });
+          });
+      }
+
+      const body = {
+        llm_metadata: {
+          model_name: llmModel,
+          llm_type: AZURE_CHAT_OPENAI_LLM_TYPE,
+        },
+        messages: [
+          userRole,
+        ],
+      };
+      if (responseFormat === JSON_OBJECT_RESPONSE_FORMAT) {
+        body.response_format = {
+          type: JSON_OBJECT_RESPONSE_FORMAT,
+        };
+        body.messages.push({
+          role: SYSTEM_ROLE,
+          content: 'You are a helpful assistant designed to output JSON.',
+        });
+      }
+
+      return body;
+    };
+
+    // Validate inputs
     if (!hasText(prompt)) {
       throw new Error('Invalid prompt received');
     }
+    if (hasImageUrls && !Array.isArray(imageUrls)) {
+      throw new Error('imageUrls must be an array.');
+    }
 
+    let chatSubmissionResponse;
     try {
       const startTime = process.hrtime.bigint();
-      const jobSubmissionResponse = await this.#submitJob(prompt);
-      const jobStatusResponse = await this.#pollJobStatus(jobSubmissionResponse.job_id);
-      this.#logDuration('Firefall API call', startTime);
+      const body = getBody();
+
+      chatSubmissionResponse = await this.#submitPrompt(JSON.stringify(body), '/v2/chat/completions');
+      this.#logDuration('Firefall API Chat Completion call', startTime);
+    } catch (error) {
+      this.log.error('Error while fetching data from Firefall chat API: ', error.message);
+      throw error;
+    }
+
+    if (!validateChatCompletionResponse(chatSubmissionResponse)) {
+      this.log.error(
+        'Could not obtain data from Firefall: Invalid response format.',
+      );
+      throw new Error('Invalid response format.');
+    }
+    if (!chatSubmissionResponse.choices.some((ch) => hasText(ch?.message?.content))) {
+      throw new Error('Prompt completed but no output was found.');
+    }
+
+    return chatSubmissionResponse;
+  }
+
+  /**
+   * Fetches data from Firefall API.
+   * @param prompt The text prompt to provide to Firefall
+   * @returns {string} - AI response
+   */
+  async fetchCapabilityExecution(prompt) {
+    if (!hasText(prompt)) {
+      throw new Error('Invalid prompt received');
+    }
+
+    try {
+      const startTime = process.hrtime.bigint();
+
+      const body = JSON.stringify({
+        input: prompt,
+        capability_name: this.config.capabilityName,
+      });
+      const path = '/v2/capability_execution/job';
+
+      const jobSubmissionResponse = await this.#submitPrompt(body, path);
+      const jobStatusResponse = await this.#pollJobStatus(jobSubmissionResponse.job_id, path);
+      this.#logDuration('Firefall API Capability Execution call', startTime);
 
       const { output } = jobStatusResponse;
       if (!output || !output.capability_response) {
         throw new Error('Job completed but no output was found');
       }
 
-      if (!validateFirefallResponse(output.capability_response)) {
+      if (!validateCapabilityExecutionResponse(output.capability_response)) {
         this.log.error('Could not obtain data from Firefall: Invalid response format.');
         throw new Error('Invalid response format.');
       }
@@ -189,8 +317,15 @@ export default class FirefallClient {
 
       return result.text;
     } catch (error) {
-      this.log.error('Error while fetching data from Firefall API: ', error.message);
+      this.log.error('Error while fetching data from Firefall Capability Execution API: ', error.message);
       throw error;
     }
   }
+
+  /**
+   * @deprecated since version 1.2.19. Use fetchCapabilityExecution instead.
+   */
+  async fetch(prompt) {
+    return this.fetchCapabilityExecution(prompt);
+  }
 }