@adobe/spacecat-shared-gpt-client 1.5.20 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-gpt-client-v1.6.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-gpt-client-v1.5.21...@adobe/spacecat-shared-gpt-client-v1.6.0) (2025-09-03)
+
+
+### Features
+
+* **gpt-client:** add optional system prompt to Azure OpenAI client ([#945](https://github.com/adobe/spacecat-shared/issues/945)) ([90f93e5](https://github.com/adobe/spacecat-shared/commit/90f93e5074ad0fd2df464f01b30edc4fe98b94cc))
+
+# [@adobe/spacecat-shared-gpt-client-v1.5.21](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-gpt-client-v1.5.20...@adobe/spacecat-shared-gpt-client-v1.5.21) (2025-08-25)
+
+
+### Bug Fixes
+
+* adding azure openai api client ([#931](https://github.com/adobe/spacecat-shared/issues/931)) ([3ed0204](https://github.com/adobe/spacecat-shared/commit/3ed020423a506f0a9f4abdc84b5afc64aa58a649))
+
 # [@adobe/spacecat-shared-gpt-client-v1.5.20](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-gpt-client-v1.5.19...@adobe/spacecat-shared-gpt-client-v1.5.20) (2025-08-09)
 
 

package/README.md

@@ -1,5 +1,141 @@
 # Spacecat Shared - GPT Client
 
+## Azure OpenAI
+
+The `AzureOpenAIClient` library provides a streamlined way to interact with Azure OpenAI's Chat Completions API, enabling applications to fetch AI-generated responses based on provided prompts. Designed with simplicity and efficiency in mind, this client handles all aspects of communication with Azure OpenAI, including request authentication, error handling, and response parsing.
+
+### Configuration
+
+To use the `AzureOpenAIClient`, you need to configure it with the following parameters:
+
+- `AZURE_OPENAI_ENDPOINT`: The endpoint URL for your Azure OpenAI resource (e.g., `https://your-resource.openai.azure.com`).
+- `AZURE_OPENAI_KEY`: Your API key for accessing the Azure OpenAI API.
+- `AZURE_API_VERSION`: The API version to use (e.g., `2024-02-01`).
+- `AZURE_COMPLETION_DEPLOYMENT`: The deployment name for your Azure OpenAI model (e.g., `gpt-4o`).
+
+**All parameters are required.** The client will throw an error if any of these configuration values are missing or invalid.
+
+These parameters can be set through environment variables or passed directly to the `AzureOpenAIClient.createFrom` method.
+
+### Usage Examples
+
+#### Instantiating the Azure OpenAI Client
+
+```javascript
+import AzureOpenAIClient from 'path/to/azure-openai-client';
+
+// Assuming environment variables are set
+const context = {
+  env: process.env,
+  log: console, // Using console for logging in this example
+};
+
+try {
+  const client = AzureOpenAIClient.createFrom(context);
+  console.log('AzureOpenAIClient created successfully.');
+} catch (error) {
+  console.error('Error creating AzureOpenAIClient:', error.message);
+}
+```
+
+#### Fetching Chat Completions
+
+```javascript
+/**
+ * Fetch chat completions using Azure OpenAI's Chat Completions API.
+ */
+async function fetchChatCompletion(prompt) {
+  try {
+    const client = AzureOpenAIClient.createFrom({
+      env: {
+        AZURE_OPENAI_ENDPOINT: 'https://your-resource.openai.azure.com',
+        AZURE_OPENAI_KEY: 'your-api-key',
+        AZURE_API_VERSION: '2024-02-01',
+        AZURE_COMPLETION_DEPLOYMENT: 'gpt-4o',
+      },
+      log: console,
+    });
+
+    const response = await client.fetchChatCompletion(prompt);
+    console.log('Response:', JSON.stringify(response));
+  } catch (error) {
+    console.error('Failed to fetch chat completion:', error.message);
+  }
+}
+
+fetchChatCompletion('What is the capital of France?');
+```
+
+#### Using Images with Chat Completions
+
+```javascript
+/**
+ * Fetch chat completions with image analysis using Azure OpenAI.
+ */
+async function fetchChatCompletionWithImages(prompt, imageUrls) {
+  try {
+    const client = AzureOpenAIClient.createFrom({
+      env: {
+        AZURE_OPENAI_ENDPOINT: 'https://your-resource.openai.azure.com',
+        AZURE_OPENAI_KEY: 'your-api-key',
+        AZURE_API_VERSION: '2024-02-01',
+        AZURE_COMPLETION_DEPLOYMENT: 'gpt-4o',
+      },
+      log: console,
+    });
+
+    const options = {
+      imageUrls: imageUrls, // Array of image URLs or base64 data
+    };
+
+    const response = await client.fetchChatCompletion(prompt, options);
+    console.log('Response:', JSON.stringify(response));
+  } catch (error) {
+    console.error('Failed to fetch chat completion with images:', error.message);
+  }
+}
+
+// Example with image URLs
+fetchChatCompletionWithImages(
+  'Identify all food items in this image',
+  ['https://example.com/food-image.jpg', 'data:image/png;base64,iVBORw0KGgoAAAA...=']
+);
+```
+
+#### Requesting JSON Responses
+
+```javascript
+/**
+ * Fetch chat completions with JSON response format.
+ */
+async function fetchJSONResponse(prompt) {
+  try {
+    const client = AzureOpenAIClient.createFrom({
+      env: {
+        AZURE_OPENAI_ENDPOINT: 'https://your-resource.openai.azure.com',
+        AZURE_OPENAI_KEY: 'your-api-key',
+        AZURE_API_VERSION: '2024-02-01',
+        AZURE_COMPLETION_DEPLOYMENT: 'gpt-4o',
+      },
+      log: console,
+    });
+
+    const options = {
+      responseFormat: 'json_object',
+    };
+
+    const response = await client.fetchChatCompletion(prompt, options);
+    console.log('JSON Response:', JSON.stringify(response));
+  } catch (error) {
+    console.error('Failed to fetch JSON response:', error.message);
+  }
+}
+
+fetchJSONResponse('Provide a list of 3 colors in JSON format');
+```
+
+Ensure that you replace `'path/to/azure-openai-client'` with the actual path to the `AzureOpenAIClient` class in your project and adjust the configuration parameters according to your Azure OpenAI resource credentials.
+
 ## Firefall
 The `FirefallClient` library offers a streamlined way to interact with the Firefall API, enabling applications to fetch insights, recommendations, and codes based on provided prompts. Designed with simplicity and efficiency in mind, this client handles all aspects of communication with the Firefall API, including request authentication, error handling, and response parsing.
 

package/package.json

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

package/src/clients/azure-openai-client.js

@@ -0,0 +1,218 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { createUrl } from '@adobe/fetch';
+import { hasText, isObject, isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import { fetch as httpFetch, sanitizeHeaders } from '../utils.js';
+
+const USER_ROLE_IMAGE_URL_TYPE = 'image_url';
+const USER_ROLE_TEXT_TYPE = 'text';
+const SYSTEM_ROLE = 'system';
+const USER_ROLE = 'user';
+const JSON_OBJECT_RESPONSE_FORMAT = 'json_object';
+
+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 AzureOpenAIClient {
+  static createFrom(context) {
+    const { log = console } = context;
+
+    const {
+      AZURE_OPENAI_ENDPOINT: apiEndpoint,
+      AZURE_OPENAI_KEY: apiKey,
+      AZURE_API_VERSION: apiVersion,
+      AZURE_COMPLETION_DEPLOYMENT: deploymentName,
+    } = context.env;
+
+    if (!isValidUrl(apiEndpoint)) {
+      throw new Error('Missing Azure OpenAI API endpoint');
+    }
+
+    if (!hasText(apiKey)) {
+      throw new Error('Missing Azure OpenAI API key');
+    }
+
+    if (!hasText(apiVersion)) {
+      throw new Error('Missing Azure OpenAI API version');
+    }
+
+    if (!hasText(deploymentName)) {
+      throw new Error('Missing Azure OpenAI deployment name');
+    }
+
+    return new AzureOpenAIClient({
+      apiEndpoint,
+      apiKey,
+      apiVersion,
+      deploymentName,
+    }, log);
+  }
+
+  /**
+   * Creates a new Azure OpenAI client
+   *
+   * @param {Object} config - The configuration object.
+   * @param {string} config.apiEndpoint - The API endpoint for Azure OpenAI.
+   * @param {string} config.apiKey - The API Key for Azure OpenAI.
+   * @param {string} config.apiVersion - The API version for Azure OpenAI.
+   * @param {string} config.deploymentName - The deployment name for Azure OpenAI.
+   * @param {Object} log - The Logger.
+   * @returns {AzureOpenAIClient} - the Azure OpenAI client.
+   */
+  constructor(config, log) {
+    this.config = config;
+    this.log = log;
+  }
+
+  #logDuration(message, startTime) {
+    const endTime = process.hrtime.bigint();
+    const duration = (endTime - startTime) / BigInt(1e6);
+    this.log.debug(`${message}: took ${duration}ms`);
+  }
+
+  /**
+   * Submit a prompt to the Azure OpenAI API.
+   * @param body The body of the request.
+   * @param path The Azure OpenAI API path.
+   * @returns {Promise<unknown>}
+   */
+  async #submitPrompt(body, path) {
+    const url = createUrl(`${this.config.apiEndpoint}${path}?api-version=${this.config.apiVersion}`);
+    const headers = {
+      'Content-Type': 'application/json',
+      'api-key': this.config.apiKey,
+    };
+
+    this.log.info(`[Azure OpenAI API Call]: ${url}, Headers: ${JSON.stringify(sanitizeHeaders(headers))}`);
+
+    const response = await httpFetch(url, {
+      method: 'POST',
+      headers,
+      body,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new Error(`API call failed with status code ${response.status} and body: ${errorBody}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Fetches data from Azure OpenAI Chat Completion API.
+   * @param prompt The text prompt to provide to Azure OpenAI
+   * @param options The options for the call, with optional properties:
+   *          - imageUrls: An array of URLs of the images to provide to Azure OpenAI
+   *          - responseFormat: The response format to request from Azure OpenAI
+   *            (accepts: json_object)
+   * @returns {Object} - AI response
+   */
+  async fetchChatCompletion(prompt, options = {}) {
+    const {
+      imageUrls,
+      responseFormat,
+      systemPrompt,
+    } = 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 = {
+        messages: [
+          userRole,
+        ],
+      };
+
+      if (systemPrompt) {
+        body.messages.unshift({
+          role: SYSTEM_ROLE,
+          content: systemPrompt,
+        });
+      } else if (responseFormat === JSON_OBJECT_RESPONSE_FORMAT) {
+        body.response_format = {
+          type: JSON_OBJECT_RESPONSE_FORMAT,
+        };
+        body.messages.unshift({
+          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 body = getBody();
+
+      chatSubmissionResponse = await this.#submitPrompt(JSON.stringify(body), `/openai/deployments/${this.config.deploymentName}/chat/completions`);
+      this.#logDuration('Azure OpenAI API Chat Completion call', startTime);
+    } catch (error) {
+      this.log.error('Error while fetching data from Azure OpenAI chat API: ', error.message);
+      throw error;
+    }
+
+    if (!validateChatCompletionResponse(chatSubmissionResponse)) {
+      this.log.error(
+        'Could not obtain data from Azure OpenAI: 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;
+  }
+}

package/src/clients/index.d.ts

@@ -12,111 +12,51 @@
 
 import type { UniversalContext } from '@adobe/helix-universal';
 
-export class FirefallClient {
+export class AzureOpenAIClient {
   /**
-   * Creates a new FirefallClient instance from the given UniversalContext.
-   * @param {UniversalContext} context The UniversalContext to use for creating the FirefallClient.
-   * @returns {FirefallClient} The FirefallClient instance.
+   * Creates a new AzureOpenAIClient instance from the given UniversalContext.
+   * @param {UniversalContext} context - The UniversalContext to use for creating the
+   *   AzureOpenAIClient.
+   * @returns {AzureOpenAIClient} The AzureOpenAIClient instance.
    */
-  static createFrom(context: UniversalContext): FirefallClient;
+  static createFrom(context: UniversalContext): AzureOpenAIClient;
 
   /**
-   * Sends the given prompt to the Firefall GPT API and returns the response.
-   * @param {string} prompt The prompt to send to the Firefall GPT API.
-   * @returns {Promise<string>} The response from the Firefall GPT API.
-   * @deprecated since version 1.2.19. Use fetchCapabilityExecution instead.
-   */
-  fetch(prompt: string): Promise<string>;
-
-  /**
-   * Fetches data from Firefall Chat Completion API.
+   * Fetches data from Azure OpenAI Chat Completion API.
    *
-   * @param {string} prompt - The text prompt to provide to Firefall
+   * @param {string} prompt - The text prompt to provide to Azure OpenAI
    * @param {object} [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.
-   * JSON mode is only currently supported with the following models: gpt-35-turbo-1106, gpt-4-turbo
+   * - imageUrls: An array of URLs of the images to provide to Azure OpenAI
+   * - responseFormat: The response format to request from Azure OpenAI (accepts: json_object)
    * @returns {Promise<object>} A promise that resolves to an object containing the chat completion.
    *
    * The returned object has the following structure:
    *
    * @example
    * {
-   *   "conversation_identifier": string | null,
-   *   "query_id": string | null,
+   *   "id": string,
+   *   "object": string,
+   *   "created": number,
    *   "model": string,
    *   "choices": [
    *     {
-   *       "finish_reason": string,
    *       "index": number,
    *       "message": {
    *         "role": string,
-   *         "content": string,
-   *         "function_call": object | null
+   *         "content": string
    *       },
-   *       "content_filter_results": {
-   *         "hate": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         },
-   *         "self_harm": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         },
-   *         "sexual": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         },
-   *         "violence": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         }
-   *       },
-   *       "logprobs": object | null
+   *       "finish_reason": string
    *     }
    *   ],
-   *   "created_at": string,
    *   "usage": {
-   *     "completion_tokens": number,
    *     "prompt_tokens": number,
+   *     "completion_tokens": number,
    *     "total_tokens": number
-   *   },
-   *   "prompt_filter_results": [
-   *     {
-   *       "prompt_index": number,
-   *       "content_filter_results": {
-   *         "hate": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         },
-   *         "jailbreak": {
-   *           "filtered": boolean,
-   *           "detected": boolean
-   *         },
-   *         "self_harm": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         },
-   *         "sexual": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         },
-   *         "violence": {
-   *           "filtered": boolean,
-   *           "severity": string
-   *         }
-   *       }
-   *     }
-   *   ]
+   *   }
    * }
    */
-  fetchChatCompletion(prompt: string, options?: object): Promise<object>;
-
-  /**
-   * Fetches data from Firefall API.
-   * @param prompt The text prompt to provide to Firefall
-   * @returns {Promise<string>} - AI response
-   */
-  fetchCapabilityExecution(prompt: string): Promise<string>;
+  fetchChatCompletion(prompt: string, options?: {
+    imageUrls?: string[];
+    responseFormat?: string;
+  }): Promise<object>;
 }

package/src/index.js

@@ -12,8 +12,10 @@
 
 import FirefallClient from './clients/firefall-client.js';
 import GenvarClient from './clients/genvar-client.js';
+import AzureOpenAIClient from './clients/azure-openai-client.js';
 
 export {
   FirefallClient,
   GenvarClient,
+  AzureOpenAIClient,
 };