feat: Add Langchain integration

eslint.config.js

@@ -33,6 +33,20 @@ export default [
       'jsdoc/require-jsdoc': 'off'
     }
   },
+  {
+    files: [
+      '**/packages/orchestration/src/client/api/default-api.ts'
+    ],
+    rules: {
+      '@typescript-eslint/explicit-module-boundary-types': 'off'
+    }
+  },
+  {
+    files: ['packages/langchain/**/*.ts'],
+    rules: {
+      'import/no-internal-modules': 'off'
+    }
+  },
   {
     ignores: ['**/dist-cjs/**/*']
   }

packages/ai-api/package.json

@@ -29,7 +29,8 @@
     "check:public-api": "node --loader ts-node/esm ../../scripts/check-public-api-cli.ts"
   },
   "dependencies": {
-    "@sap-ai-sdk/core": "workspace:^"
+    "@sap-ai-sdk/core": "workspace:^",
+    "@sap-cloud-sdk/util": "^3.20.0"
   },
   "devDependencies": {
     "typescript": "^5.5.4",

packages/foundation-models/src/openai/openai-response.test.ts

@@ -0,0 +1,47 @@
+import { parseMockResponse } from '../../../../test-util/mock-http.js';
+import { OpenAiChatCompletionResponse } from './openai-response.js';
+import { OpenAiChatCompletionOutput } from './openai-types.js';
+
+describe('OpenAI response', () => {
+  const mockResponse = parseMockResponse<OpenAiChatCompletionOutput>(
+    'foundation-models',
+    'openai-chat-completion-success-response.json'
+  );
+  const rawResponse = {
+    data: mockResponse,
+    status: 200,
+    headers: {},
+    request: {}
+  };
+  const openAiChatClientResponse = new OpenAiChatCompletionResponse(
+    rawResponse
+  );
+
+  it('should initialize with raw response', () => {
+    expect(openAiChatClientResponse.rawResponse).toBe(rawResponse);
+  });
+
+  it('should return the completion response', () => {
+    expect(openAiChatClientResponse.data).toBe(mockResponse);
+  });
+
+  it('should get token usage', () => {
+    expect(openAiChatClientResponse.getTokenUsage()).toMatchObject({
+      completion_tokens: expect.any(Number),
+      prompt_tokens: expect.any(Number),
+      total_tokens: expect.any(Number)
+    });
+  });
+
+  it('should return default choice index with convenience functions', () => {
+    expect(openAiChatClientResponse.getFinishReason()).toBe('stop');
+    expect(openAiChatClientResponse.getContent()).toBe(
+      'The deepest place on Earth is located in the Western Pacific Ocean and is known as the Mariana Trench.'
+    );
+  });
+
+  it('should return undefined when convenience function is called with incorrect index', () => {
+    expect(openAiChatClientResponse.getFinishReason(1)).toBeUndefined();
+    expect(openAiChatClientResponse.getContent(1)).toBeUndefined();
+  });
+});

packages/langchain/README.md

@@ -0,0 +1,102 @@
+# @sap-ai-sdk/langchain
+This package provides LangChain model clients, built on top of the `@sap-ai-sdk`.
+
+## Table of Contents
+1. [Installation](#installation)
+2. [Pre-requisites](#pre-requisites)
+3. [Usage](#usage)
+    - [Client Initialization](#client-initialization)
+    - [Chat Clients](#chat-clients)
+    - [Embedding Clients](#embedding-clients)
+4. [Support, Feedback, Contribution](#support-feedback-contribution)
+5. [License](#license)
+
+## Installation
+```
+$ npm install @sap-ai-sdk/langchain
+```
+
+## Pre-requisites
+- [Enable the AI Core service in BTP](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/initial-setup).
+- Bind the service to your application.
+- Ensure the project is configured with Node.js v20 or higher, along with native ESM support.
+- For testing your application locally:
+  - Download a service key for your AI Core service instance.
+  - Create a `.env` file in the sample-code directory.
+  - Add an entry `AICORE_SERVICE_KEY='<content-of-service-key>'`.
+
+## Usage
+This package provides both chat and embedding clients, currently supporting Azure OpenAI.
+All clients comply with [LangChain's interface](https://js.langchain.com/docs/introduction).
+
+### Client Initialization
+To initialize a client, you only need to provide the model name:
+
+```ts
+import { AzureOpenAiChatClient } from '@sap-ai-sdk/langchain';
+const chatClient = new AzureOpenAiChatClient({ modelName: 'gpt-4o' });
+```
+
+In addition to the default parameters of the model vendor (e.g. OpenAI) and LangChain, there are also SDK-specific parameters, which you can use to narrow down the search for the model you want to use:
+
+```ts
+const chatClient = new AzureOpenAiChatClient({
+  modelName: 'gpt-4o',
+  modelVersion: '24-07-2021',
+  resourceGroup: 'my-resource-group'
+});
+```
+
+### Chat Clients
+The chat clients allow you to interact with Azure OpenAI chat models, accessible via SAP Gen AI Hub. 
+To invoke the client, you only have a to pass a prompt.
+
+#### Simple Example
+```ts
+const response = await chatClient.invoke("What's the capital of France?");
+```
+
+#### Advanced Example with Templating and Output Parsing
+```ts
+import { AzureOpenAiChatClient } from '@sap-ai-sdk/langchain';
+import { StringOutputParser } from '@langchain/core/output_parsers';
+import { ChatPromptTemplate } from '@langchain/core/prompts';
+
+const client = new AzureOpenAiChatClient({ modelName: 'gpt-35-turbo' });
+const promptTemplate = ChatPromptTemplate.fromMessages([
+  ['system', 'Answer the following in {language}:'],
+  ['user', '{text}']
+]);
+const parser = new StringOutputParser();
+const llmChain = promptTemplate.pipe(client).pipe(parser);
+const response = await llmChain.invoke({
+  language: 'german',
+  text: 'What is the capital of France?'
+});
+```
+
+### Embedding Clients
+Embedding clients allow embedding either text or documents (represented as arrays of strings).
+
+#### Embed Text
+```ts
+const embeddedText = await embeddingClient.embedQuery(
+  'Paris is the capital of France.'
+);
+```
+
+#### Embed Documents
+```ts
+const embeddedDocument = await embeddingClient.embedDocuments([
+  'Page 1: Paris is the capital of France.',
+  'Page 2: It is a beautiful city.'
+]);
+```
+
+## Support, Feedback, Contribution
+This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/SAP/ai-sdk-js/issues).
+
+Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](https://github.com/SAP/ai-sdk-js/blob/main/CONTRIBUTING.md).
+
+## License
+The SAP Cloud SDK for AI is released under the [Apache License Version 2.0.](http://www.apache.org/licenses/)

packages/langchain/internal.d.ts

@@ -0,0 +1,3 @@
+// eslint-disable-next-line import/no-internal-modules
+export * from './dist/internal.js';
+// # sourceMappingURL=internal.d.ts.map

packages/langchain/jest.config.mjs

@@ -0,0 +1,5 @@
+import config from '../../jest.config.mjs';
+export default {
+  ...config,
+  displayName: 'langchain',
+};

packages/langchain/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sap-ai-sdk/langchain",
+  "version": "0.0.0",
+  "description": "LangChain clients based on the @sap-ai-sdk",
+  "license": "Apache-2.0",
+  "keywords": [
+    "sap-ai-sdk",
+    "langchain"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "internal.js",
+    "internal.d.ts"
+  ],
+  "scripts": {
+    "compile": "tsc",
+    "compile:cjs": "tsc -p tsconfig.cjs.json",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "lint": "eslint \"**/*.ts\" && prettier . --config ../../.prettierrc --ignore-path ../../.prettierignore -c",
+    "lint:fix": "eslint \"**/*.ts\" --fix && prettier . --config ../../.prettierrc --ignore-path ../../.prettierignore -w --log-level error",
+    "check:public-api": "node --loader ts-node/esm ../../scripts/check-public-api-cli.ts"
+  },
+  "dependencies": {
+    "@sap-ai-sdk/ai-api": "workspace:^",
+    "@sap-ai-sdk/foundation-models": "workspace:^",
+    "@langchain/core": "0.3.1",
+    "zod-to-json-schema": "^3.23.2",
+    "@sap-cloud-sdk/util": "^3.20.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  }
+}

packages/langchain/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  AzureOpenAiChatClient,
+  AzureOpenAiEmbeddingClient
+} from './openai/index.js';
+export type {
+  AzureOpenAiChatModelParams,
+  AzureOpenAiEmbeddingModelParams,
+  AzureOpenAiChatCallOptions
+} from './openai/index.js';

packages/langchain/src/internal.ts

@@ -0,0 +1 @@
+export * from './openai/index.js';

packages/langchain/src/openai/__snapshots__/util.test.ts.snap

@@ -0,0 +1,50 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Mapping Functions should parse an OpenAi response to a (Langchain) chat response 1`] = `
+{
+  "generations": [
+    {
+      "generationInfo": {
+        "finish_reason": "stop",
+        "function_call": undefined,
+        "index": 0,
+        "tool_calls": undefined,
+      },
+      "message": {
+        "id": [
+          "langchain_core",
+          "messages",
+          "AIMessage",
+        ],
+        "kwargs": {
+          "additional_kwargs": {
+            "finish_reason": "stop",
+            "function_call": undefined,
+            "index": 0,
+            "tool_call_id": "",
+            "tool_calls": undefined,
+          },
+          "content": "The deepest place on Earth is located in the Western Pacific Ocean and is known as the Mariana Trench.",
+          "invalid_tool_calls": [],
+          "response_metadata": {},
+          "tool_calls": [],
+        },
+        "lc": 1,
+        "type": "constructor",
+      },
+      "text": "The deepest place on Earth is located in the Western Pacific Ocean and is known as the Mariana Trench.",
+    },
+  ],
+  "llmOutput": {
+    "created": 1725457796,
+    "id": "chatcmpl-A3kgOwg9B6j87n0IkoCFCUCxRSwQZ",
+    "model": "gpt-4-32k",
+    "object": "chat.completion",
+    "tokenUsage": {
+      "completionTokens": 22,
+      "promptTokens": 15,
+      "totalTokens": 37,
+    },
+  },
+}
+`;

packages/langchain/src/openai/chat.ts

@@ -0,0 +1,78 @@
+import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import { BaseMessage } from '@langchain/core/messages';
+import type { ChatResult } from '@langchain/core/outputs';
+import { AzureOpenAiChatClient as AzureOpenAiChatClientBase } from '@sap-ai-sdk/foundation-models';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { AzureOpenAiChatModel } from '@sap-ai-sdk/core';
+import { mapLangchainToAiClient, mapOutputToChatResult } from './util.js';
+import type {
+  AzureOpenAiChatCallOptions,
+  AzureOpenAiChatModelParams
+} from './types.js';
+
+/**
+ * LangChain chat client for Azure OpenAI consumption on SAP BTP.
+ */
+export class AzureOpenAiChatClient
+  extends BaseChatModel<AzureOpenAiChatCallOptions>
+  implements AzureOpenAiChatModelParams
+{
+  modelName: AzureOpenAiChatModel;
+  modelVersion?: string;
+  resourceGroup?: string;
+  temperature?: number;
+  top_p?: number;
+  logit_bias?: Record<string, unknown>;
+  user?: string;
+  n?: number;
+  presence_penalty?: number;
+  frequency_penalty?: number;
+  stop?: string | string[];
+  max_tokens?: number;
+  private openAiChatClient: AzureOpenAiChatClientBase;
+
+  constructor(fields: AzureOpenAiChatModelParams) {
+    super(fields);
+    this.openAiChatClient = new AzureOpenAiChatClientBase(fields);
+    this.modelName = fields.modelName;
+    this.modelVersion = fields.modelVersion;
+    this.resourceGroup = fields.resourceGroup;
+    this.temperature = fields.temperature;
+    this.top_p = fields.top_p;
+    this.logit_bias = fields.logit_bias;
+    this.user = fields.user;
+    this.n = fields.n;
+    this.stop = fields.stop;
+    this.presence_penalty = fields.presence_penalty;
+    this.frequency_penalty = fields.frequency_penalty;
+    this.max_tokens = fields.max_tokens;
+  }
+
+  _llmType(): string {
+    return 'azure_openai';
+  }
+
+  override async _generate(
+    messages: BaseMessage[],
+    options: typeof this.ParsedCallOptions,
+    runManager?: CallbackManagerForLLMRun
+  ): Promise<ChatResult> {
+    const res = await this.caller.callWithOptions(
+      {
+        signal: options.signal
+      },
+      () =>
+        this.openAiChatClient.run(
+          mapLangchainToAiClient(this, options, messages),
+          options.requestConfig
+        )
+    );
+
+    // we currently do not support streaming
+    await runManager?.handleLLMNewToken(
+      typeof res.getContent() === 'string' ? (res.getContent() as string) : ''
+    );
+
+    return mapOutputToChatResult(res.data);
+  }
+}