diff --git a/.changeset/nice-emus-train.md b/.changeset/nice-emus-train.md new file mode 100644 index 000000000..92b6d87ec --- /dev/null +++ b/.changeset/nice-emus-train.md @@ -0,0 +1,5 @@ +--- +'@sap-ai-sdk/orchestration': minor +--- + +[feat] Update orchestration specification to 0.115.19 diff --git a/packages/orchestration/src/client/api/schema/dpi-config.ts b/packages/orchestration/src/client/api/schema/dpi-config.ts index afc07d364..45e43fa2c 100644 --- a/packages/orchestration/src/client/api/schema/dpi-config.ts +++ b/packages/orchestration/src/client/api/schema/dpi-config.ts @@ -35,4 +35,8 @@ export type DpiConfig = { */ enabled?: boolean; }; + /** + * Type of masking method to be used for file inputs. Required if file inputs are provided. + */ + mask_file_input_method?: 'anonymization' | 'skip'; }; diff --git a/packages/orchestration/src/client/api/schema/embedding-base-64-string.ts b/packages/orchestration/src/client/api/schema/embedding-base-64-string.ts new file mode 100644 index 000000000..8078f7268 --- /dev/null +++ b/packages/orchestration/src/client/api/schema/embedding-base-64-string.ts @@ -0,0 +1,10 @@ +/* + * Copyright (c) 2026 SAP SE or an SAP affiliate company. All rights reserved. + * + * This is a generated file powered by the SAP Cloud SDK for JavaScript. + */ + +/** + * A single base64 string representing the embedding. + */ +export type EmbeddingBase64String = string; diff --git a/packages/orchestration/src/client/api/schema/embedding-float-array.ts b/packages/orchestration/src/client/api/schema/embedding-float-array.ts new file mode 100644 index 000000000..3b3eafac6 --- /dev/null +++ b/packages/orchestration/src/client/api/schema/embedding-float-array.ts @@ -0,0 +1,10 @@ +/* + * Copyright (c) 2026 SAP SE or an SAP affiliate company. All rights reserved. + * + * This is a generated file powered by the SAP Cloud SDK for JavaScript. + */ + +/** + * An array of floating point numbers representing the embedding. + */ +export type EmbeddingFloatArray = number[]; diff --git a/packages/orchestration/src/client/api/schema/embedding-multi-format.ts b/packages/orchestration/src/client/api/schema/embedding-multi-format.ts new file mode 100644 index 000000000..654fe46ed --- /dev/null +++ b/packages/orchestration/src/client/api/schema/embedding-multi-format.ts @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2026 SAP SE or an SAP affiliate company. All rights reserved. + * + * This is a generated file powered by the SAP Cloud SDK for JavaScript. + */ + +/** + * A dictionary mapping encoding format names to their embeddings. Used when multiple encoding formats are requested (Cohere-specific). + */ +export type EmbeddingMultiFormat = { + /** + * Float encoding format - array of floating point numbers + */ + float?: number[]; + /** + * Int8 encoding format - array of 8-bit integers + */ + int8?: number[]; + /** + * Uint8 encoding format - array of unsigned 8-bit integers + */ + uint8?: number[]; + /** + * Base64 encoding format - base64 encoded string + */ + base64?: string; + /** + * Binary encoding format - array of integers + */ + binary?: number[]; + /** + * Ubinary encoding format - array of unsigned integers + */ + ubinary?: number[]; +}; diff --git a/packages/orchestration/src/client/api/schema/embedding.ts b/packages/orchestration/src/client/api/schema/embedding.ts index e0eea646f..9f2c000bf 100644 --- a/packages/orchestration/src/client/api/schema/embedding.ts +++ b/packages/orchestration/src/client/api/schema/embedding.ts @@ -3,8 +3,13 @@ * * This is a generated file powered by the SAP Cloud SDK for JavaScript. */ - +import type { EmbeddingFloatArray } from './embedding-float-array.js'; +import type { EmbeddingBase64String } from './embedding-base-64-string.js'; +import type { EmbeddingMultiFormat } from './embedding-multi-format.js'; /** * Representation of the 'Embedding' schema. */ -export type Embedding = number[] | string; +export type Embedding = + | EmbeddingFloatArray + | EmbeddingBase64String + | EmbeddingMultiFormat; diff --git a/packages/orchestration/src/client/api/schema/embeddings-input.ts b/packages/orchestration/src/client/api/schema/embeddings-input.ts index d7c9202fd..b53ae3393 100644 --- a/packages/orchestration/src/client/api/schema/embeddings-input.ts +++ b/packages/orchestration/src/client/api/schema/embeddings-input.ts @@ -9,5 +9,13 @@ import type { EmbeddingsInputText } from './embeddings-input-text.js'; */ export type EmbeddingsInput = { text: EmbeddingsInputText; - type?: 'text' | 'document' | 'query'; + type?: + | 'text' + | 'document' + | 'query' + | 'search_document' + | 'search_query' + | 'classification' + | 'clustering' + | 'image'; }; diff --git a/packages/orchestration/src/client/api/schema/embeddings-model-params.ts b/packages/orchestration/src/client/api/schema/embeddings-model-params.ts index b1a8995b4..28fa50d42 100644 --- a/packages/orchestration/src/client/api/schema/embeddings-model-params.ts +++ b/packages/orchestration/src/client/api/schema/embeddings-model-params.ts @@ -3,7 +3,7 @@ * * This is a generated file powered by the SAP Cloud SDK for JavaScript. */ - +import type { EncodingFormat } from './encoding-format.js'; /** * Additional parameters for generating input's embeddings. Default values are used for mandatory parameters. */ @@ -14,9 +14,9 @@ export type EmbeddingsModelParams = { */ dimensions?: number; /** - * OpenAI's spec allows for 'float' and 'base64' encoding formats. + * The format to return the embeddings in. Can be a single format or an array of formats. OpenAI's spec allows for 'float' and 'base64' encoding formats. * */ - encoding_format?: 'float' | 'base64' | 'binary'; + encoding_format?: EncodingFormat | EncodingFormat[]; normalize?: boolean; } & Record; diff --git a/packages/orchestration/src/client/api/schema/encoding-format.ts b/packages/orchestration/src/client/api/schema/encoding-format.ts new file mode 100644 index 000000000..a646f779f --- /dev/null +++ b/packages/orchestration/src/client/api/schema/encoding-format.ts @@ -0,0 +1,16 @@ +/* + * Copyright (c) 2026 SAP SE or an SAP affiliate company. All rights reserved. + * + * This is a generated file powered by the SAP Cloud SDK for JavaScript. + */ + +/** + * Encoding format for embeddings. + */ +export type EncodingFormat = + | 'float' + | 'base64' + | 'binary' + | 'int8' + | 'uint8' + | 'ubinary'; diff --git a/packages/orchestration/src/client/api/schema/index.ts b/packages/orchestration/src/client/api/schema/index.ts index b654e436e..151ed56a5 100644 --- a/packages/orchestration/src/client/api/schema/index.ts +++ b/packages/orchestration/src/client/api/schema/index.ts @@ -11,11 +11,15 @@ export * from './embeddings-input-text.js'; export * from './embeddings-module-configs.js'; export * from './embeddings-model-config.js'; export * from './embeddings-model-details.js'; +export * from './encoding-format.js'; export * from './embeddings-model-params.js'; export * from './embeddings-post-response.js'; export * from './embeddings-response.js'; export * from './embeddings-usage.js'; export * from './embedding-result.js'; +export * from './embedding-float-array.js'; +export * from './embedding-base-64-string.js'; +export * from './embedding-multi-format.js'; export * from './embedding.js'; export * from './chat-messages.js'; export * from './templating-chat-message.js'; diff --git a/packages/orchestration/src/index.ts b/packages/orchestration/src/index.ts index 0f34a4689..015c969c8 100644 --- a/packages/orchestration/src/index.ts +++ b/packages/orchestration/src/index.ts @@ -44,7 +44,8 @@ export type { EmbeddingModelDetails, EmbeddingModelParams, EmbeddingModuleConfig, - EmbeddingData + EmbeddingData, + OrchestrationRequestHeaders } from './orchestration-types.js'; export { isConfigReference, diff --git a/packages/orchestration/src/orchestration-client.test.ts b/packages/orchestration/src/orchestration-client.test.ts index 7acb7a2ed..66b8e806c 100644 --- a/packages/orchestration/src/orchestration-client.test.ts +++ b/packages/orchestration/src/orchestration-client.test.ts @@ -6,6 +6,7 @@ import { getOrchestrationDeploymentId } from '@sap-ai-sdk/ai-api/internal.js'; import { + aiCoreDestination, mockClientCredentialsGrantCall, mockDeploymentsList, mockInference, @@ -707,6 +708,45 @@ describe('orchestration service client', () => { expect(response._data).toEqual(mockResponse); }); + it('passes AI-Object-Store-Secret-Name header to the HTTP request', async () => { + const config: OrchestrationModuleConfig = { + promptTemplating: { + model: { + name: 'gpt-5-mini', + params: { max_tokens: 50 } + } + } + }; + + const prompt: ChatCompletionRequest = { + messages: [{ role: 'user', content: 'Hello' }] + }; + + const mockResponse = await parseMockResponse( + 'orchestration', + 'orchestration-chat-completion-success-response.json' + ); + + nock(aiCoreDestination.url, { + reqheaders: { + 'ai-resource-group': 'default', + 'AI-Object-Store-Secret-Name': 'my-object-store-secret' + } + }) + .post( + '/v2/inference/deployments/1234/v2/completion', + constructCompletionPostRequest(config, prompt) + ) + .reply(200, mockResponse); + + const response = await new OrchestrationClient(config).chatCompletion( + prompt, + { headers: { 'AI-Object-Store-Secret-Name': 'my-object-store-secret' } } + ); + + expect(response._data).toEqual(mockResponse); + }); + it('executes a request with the custom resource group', async () => { const prompt: ChatCompletionRequest = { messagesHistory: [ diff --git a/packages/orchestration/src/orchestration-client.ts b/packages/orchestration/src/orchestration-client.ts index 19db0a0bd..7cdf0d839 100644 --- a/packages/orchestration/src/orchestration-client.ts +++ b/packages/orchestration/src/orchestration-client.ts @@ -32,7 +32,8 @@ import type { ChatCompletionRequest, RequestOptions, StreamOptions, - BaseStreamOptions + BaseStreamOptions, + OrchestrationRequestHeaders } from './orchestration-types.js'; import type { OrchestrationStreamChunkResponse } from './orchestration-stream-chunk-response.js'; import type { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity'; @@ -74,9 +75,18 @@ export class OrchestrationClient { } } + /** + * Send a chat completion request to the orchestration service. + * @param request - Request containing messages, placeholder values, and message history. + * @param requestConfig - Additional request configuration. Use `requestConfig.headers` to pass service-specific headers: + * - `AI-Object-Store-Secret-Name`: Name of the object store secret used by the feedback service. + * @returns The orchestration service response. + */ async chatCompletion( request?: ChatCompletionRequest, - requestConfig?: CustomRequestConfig + requestConfig?: CustomRequestConfig & { + headers?: OrchestrationRequestHeaders; + } ): Promise { requestConfig?.signal?.throwIfAborted(); if (isConfigReference(this.config) && request?.messages?.length) { @@ -92,11 +102,22 @@ export class OrchestrationClient { return new OrchestrationResponse(response); } + /** + * Create a streaming chat completion request to the orchestration service. + * @param request - Request containing messages, placeholder values, and message history. + * @param signal - An abort signal to cancel the request. + * @param options - Streaming options, e.g., for input/output filtering. + * @param requestConfig - Additional request configuration. Use `requestConfig.headers` to pass service-specific headers: + * - `AI-Object-Store-Secret-Name`: Name of the object store secret used by the feedback service. + * @returns The orchestration stream response. + */ async stream( request?: ChatCompletionRequest, signal?: AbortSignal, options?: StreamOptions, - requestConfig?: CustomRequestConfig + requestConfig?: CustomRequestConfig & { + headers?: OrchestrationRequestHeaders; + } ): Promise> { const controller = new AbortController(); if (signal) { diff --git a/packages/orchestration/src/orchestration-embedding-response.ts b/packages/orchestration/src/orchestration-embedding-response.ts index 5d4ebc9b4..2b21cd786 100644 --- a/packages/orchestration/src/orchestration-embedding-response.ts +++ b/packages/orchestration/src/orchestration-embedding-response.ts @@ -22,7 +22,6 @@ export class OrchestrationEmbeddingResponse { * @returns Array of embedding data objects containing both vectors, indices, and object types. */ getEmbeddings(): EmbeddingData[] { - // TODO: Remove non-null assertion when final_result is made mandatory in the schema return this._data.final_result.data.map((result: EmbeddingResult) => ({ embedding: result.embedding, index: result.index, diff --git a/packages/orchestration/src/orchestration-types.ts b/packages/orchestration/src/orchestration-types.ts index 3feaeb8ec..03c46724e 100644 --- a/packages/orchestration/src/orchestration-types.ts +++ b/packages/orchestration/src/orchestration-types.ts @@ -26,7 +26,8 @@ import type { EmbeddingsModelDetails as OriginalEmbeddingsModelDetails, EmbeddingsModelParams as OriginalEmbeddingsModelParams, SAPDocumentTranslationInput, - SAPDocumentTranslationOutput + SAPDocumentTranslationOutput, + Embedding } from './client/api/schema/index.js'; /** @@ -353,6 +354,23 @@ export function isOrchestrationModuleConfigList( } } +/** + * Service-specific headers for orchestration requests. + * @remarks + * `AI-Resource-Group` is configured via the `deploymentConfig` constructor parameter, not here. + */ +export interface OrchestrationRequestHeaders { + /** + * Name of the object store secret used by the feedback service. + */ + 'AI-Object-Store-Secret-Name'?: string; + [key: string]: any; + /** + * Use the `deploymentConfig` constructor parameter to set the resource group instead. + */ + 'AI-Resource-Group'?: never; +} + /** * Request options for orchestration. */ @@ -828,9 +846,9 @@ export interface EmbeddingData { */ object: 'embedding'; /** - * The embedding vector, either as a number array or base64-encoded string. + * The embedding vector, either as a number array, a base64-encoded string, or multiple formats in case multiple output formats were requested. */ - embedding: number[] | string; + embedding: Embedding; /** * The index of the embedding in the list of embeddings. */ diff --git a/packages/orchestration/src/spec/api.yaml b/packages/orchestration/src/spec/api.yaml index c21b9b471..f71306db8 100644 --- a/packages/orchestration/src/spec/api.yaml +++ b/packages/orchestration/src/spec/api.yaml @@ -40,6 +40,9 @@ paths: summary: orchestrated completion inference description: Run an orchestrated completion inference request operationId: orchestration.v2.endpoints.create + parameters: + - $ref: '#/components/parameters/AIResourceGroup' + - $ref: '#/components/parameters/AIObjectStoreSecretName' requestBody: required: true content: @@ -82,12 +85,146 @@ paths: application/json: schema: $ref: '#/components/schemas/EmbeddingsPostResponse' + examples: + array_embeddings: + summary: Array format (single encoding_format) + description: Standard response format when a single encoding format is requested. Used by OpenAI, AWS Bedrock, VertexAI, Nvidia, and Cohere with single format. + value: + request_id: 'd4a67ea1-2bf9-4df7-8105-d48203ccff76' + final_result: + object: 'list' + data: + - object: 'embedding' + embedding: + - 0.015282119 + - 0.013516456 + - 0.002541946 + - -0.010837519 + index: 0 + - object: 'embedding' + embedding: + - 0.035031624 + - -0.0077586817 + - 0.018221147 + - 0.00446712 + index: 1 + model: 'text-embedding-ada-002' + usage: + prompt_tokens: 5 + total_tokens: 5 + base64_embeddings: + summary: Base64 string format (single encoding_format) + description: Response format when base64 encoding format is requested. The embedding is returned as a base64-encoded string. + value: + request_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' + final_result: + object: 'list' + data: + - object: 'embedding' + embedding: '2mF6PCB0XTzHliY72Y8xvOalM6uLmZjLyu7ze9==' + index: 0 + - object: 'embedding' + embedding: '8nB7QDB1YUzImiZ82Z9ywPbmN7vMnajMzv8zf+==' + index: 1 + model: 'text-embedding-3-large' + usage: + prompt_tokens: 5 + total_tokens: 5 + cohere_multi_type_embeddings: + summary: Dictionary format (multiple encoding_formats - Cohere only) + description: Response format when multiple encoding formats are requested (Cohere-specific feature). Each result contains a dictionary mapping format names to their respective embeddings. + value: + request_id: 'f5ba36c6-a687-4e0c-b7e4-26b623256baf' + final_result: + object: 'list' + data: + - object: 'embedding' + embedding: + float: + - 0.015282119 + - 0.013516456 + - 0.002541946 + - -0.010837519 + uint8: + - 142 + - 137 + - 124 + - 106 + index: 0 + - object: 'embedding' + embedding: + float: + - 0.035031624 + - -0.0077586817 + - 0.018221147 + - 0.00446712 + uint8: + - 151 + - 119 + - 133 + - 125 + index: 1 + model: 'cohere--single-serving-embed' + usage: + prompt_tokens: 12 + total_tokens: 12 + cohere_mixed_types_embeddings: + summary: Dictionary format with mixed types (Cohere only) + description: Response format when multiple encoding formats of different types are requested (e.g., float arrays and base64 strings). + value: + request_id: '11c785a2-09c7-4b12-b86e-3a3ff7ece72e' + final_result: + object: 'dict' + data: + - object: 'embedding' + embedding: + float: + - 0.015282119 + - 0.013516456 + - 0.002541946 + - -0.010837519 + base64: '2mF6PCB0XTzHliY72Y8xvOalM6uLmZjLyu7ze9==' + index: 0 + - object: 'embedding' + embedding: + float: + - 0.035031624 + - -0.0077586817 + - 0.018221147 + - 0.00446712 + base64: '8nB7QDB1YUzImiZ82Z9ywPbmN7vMnajMzv8zf+==' + index: 1 + model: 'cohere--single-serving-embed' + usage: + prompt_tokens: 12 + total_tokens: 12 '400': $ref: '#/components/responses/BadRequest' default: $ref: '#/components/responses/CommonError' components: + parameters: + AIResourceGroup: + in: header + name: AI-Resource-Group + description: 'Feedback specific - resource group of the feedback service object store secret.' + required: false + schema: + maxLength: 253 + minLength: 3 + pattern: ^[a-zA-Z0-9][a-zA-Z0-9.-]{1,251}[a-zA-Z0-9]$ + type: string + AIObjectStoreSecretName: + in: header + name: AI-Object-Store-Secret-Name + description: 'Feedback specific - name of the feedback service object store secret.' + required: false + schema: + maxLength: 233 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string securitySchemes: Oauth2: type: oauth2 @@ -135,7 +272,17 @@ components: $ref: '#/components/schemas/EmbeddingsInputText' type: type: string - enum: ['text', 'document', 'query'] + enum: + [ + 'text', + 'document', + 'query', + 'search_document', + 'search_query', + 'classification', + 'clustering', + 'image' + ] EmbeddingsInputText: oneOf: - type: string @@ -193,6 +340,11 @@ components: default: 2 minimum: 0 maximum: 5 + EncodingFormat: + type: string + enum: [float, base64, binary, int8, uint8, ubinary] + description: Encoding format for embeddings. + EmbeddingsModelParams: type: object description: Additional parameters for generating input's embeddings. Default values are used for mandatory parameters. @@ -203,9 +355,14 @@ components: description: > The number of dimensions the resulting output embeddings should have. encoding_format: - type: string - enum: [float, base64, binary] + oneOf: + - $ref: '#/components/schemas/EncodingFormat' + - type: array + items: + $ref: '#/components/schemas/EncodingFormat' + minItems: 1 description: > + The format to return the embeddings in. Can be a single format or an array of formats. OpenAI's spec allows for 'float' and 'base64' encoding formats. normalize: type: boolean @@ -282,14 +439,52 @@ components: index: type: integer description: The index of the embedding in the list of embeddings. - Embedding: - oneOf: - - type: array + EmbeddingFloatArray: + type: array + items: + type: number + description: 'An array of floating point numbers representing the embedding. ' + EmbeddingBase64String: + type: string + description: 'A single base64 string representing the embedding.' + EmbeddingMultiFormat: + type: object + description: 'A dictionary mapping encoding format names to their embeddings. Used when multiple encoding formats are requested (Cohere-specific).' + additionalProperties: false + properties: + float: + type: array items: type: number - description: 'An array of numbers representing the embedding.' - - type: string - description: 'A single base64 string representing the embedding.' + description: 'Float encoding format - array of floating point numbers' + int8: + type: array + items: + type: integer + description: 'Int8 encoding format - array of 8-bit integers' + uint8: + type: array + items: + type: integer + description: 'Uint8 encoding format - array of unsigned 8-bit integers' + base64: + type: string + description: 'Base64 encoding format - base64 encoded string' + binary: + type: array + items: + type: integer + description: 'Binary encoding format - array of integers' + ubinary: + type: array + items: + type: integer + description: 'Ubinary encoding format - array of unsigned integers' + Embedding: + oneOf: + - $ref: '#/components/schemas/EmbeddingFloatArray' + - $ref: '#/components/schemas/EmbeddingBase64String' + - $ref: '#/components/schemas/EmbeddingMultiFormat' # Chat Completion Schemas ChatMessages: @@ -1492,6 +1687,12 @@ components: type: boolean default: false description: controls whether the input to the grounding module will be masked with the configuration supplied in the masking module + mask_file_input_method: + description: Type of masking method to be used for file inputs. Required if file inputs are provided. + type: string + enum: + - anonymization + - skip DPIEntityConfig: oneOf: