Merge remote-tracking branch 'origin/main' into refactor-ai-api-e2e-t…

…ests

merge main

.github/workflows/build.yml

@@ -36,6 +36,8 @@ jobs:
         run: pnpm check:public-api
       - name: Check dependencies
         run: pnpm check:deps
+      - name: License Check
+        uses: sap/cloud-sdk-js/.github/actions/check-license@main
 
   dependabot:
     runs-on: ubuntu-latest

.github/workflows/documentation.yaml

@@ -0,0 +1,42 @@
+name: documentation
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  grammar-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Determine Changed Files
+        id: changed-files
+        run: |
+          ALL_FILES=$(gh pr view ${{ github.event.pull_request.number }} --json files --jq '.files.[] | select(.additions > 0) | .path')
+          CHANGED_FILES="${ALL_FILES//$'\n'/,}"
+
+          echo "[DEBUG] Following files have been changed: $CHANGED_FILES"
+          echo "CHANGED_FILES=$CHANGED_FILES" >> $GITHUB_OUTPUT
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+      - name: Vale
+        # vale fails if the PR is too large, e.g. when updating API docs
+        if: ${{ github.event.pull_request.changed_files < 100 }}
+        # You may pin to the exact commit or the version.
+        # uses: errata-ai/vale-action@0da98680790f89b8d5b685de9c264f55addc971b
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          # version of 'vale' to use
+          # see https://github.com/errata-ai/vale for all releases
+          version: 3.7.1
+          # changed files. computed in the step above
+          files: ${{ steps.changed-files.outputs.CHANGED_FILES }}
+          # the separator for the file list. we are using a comma (see step above)
+          separator: ","
+          # let review dog fail if there are errors
+          fail_on_error: true
+        env:
+          # Required
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -0,0 +1,17 @@
+; Vale is a command-line tool that brings code-like linting to prose.
+; More information here: https://docs.errata.ai/vale/about/
+
+StylesPath = styles
+
+Vocab = SAP
+; MinAlertLevel = suggestion
+MinAlertLevel = warning
+WordTemplate = \b(?:%s)\b
+
+[*.md]
+BasedOnStyles = Vale, SAP
+BlockIgnores = (<(img|br|Tabs|Redirect|a|MvnBadge|embed|Csrf)\s[^>]+>+?), \
+(?s) *(import[^\n]+;)
+TokenIgnores = (<(img|br|Tabs|Redirect|a|MvnBadge|embed|Csrf)\s[^\n]+>+?)
+
+Vale.Terms = warning

CONTRIBUTING.md

@@ -5,21 +5,23 @@ When contributing to this repository, please first discuss the changes you wish
 All members of the project community must abide by the [SAP Open Source Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md).
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [a project maintainer](.reuse/dep5).
 
-Once you are ready to make a change, please test it appropriately, create a pull request and describe your change in the pull request. The owners of the repository will review your changes as soon as possible.
+Once you are ready to make a change, please test it appropriately, create a pull request and describe your change in the pull request. 
+The owners of the repository will review your changes as soon as possible.
 
 ## Project Structure
 
 This project contains multiple packages, that are managed using pnpm workspaces.
 Productive packages are located in the `packages` directory, test packages are located in the `tests` directory.
-Some of the packages are interdependent, therefore pnpm install won't work from within those packages. Run `pnpm install` in the root directory instead.
+Some of the packages are interdependent, therefore pnpm install won't work from within those packages. 
+Run `pnpm install` in the root directory instead.
 
 ## Testing
 
 All (new) functionality shall be covered by tests.
 
 ### Jest Runner Set-up
 
-If you're using the Jest Runner extension in Visual Studio Code, you'll need to add the following settings to your `settings.json` file before running the tests from VSCode:
+If you're using the Jest Runner extension in Visual Studio Code, you'll need to add the following settings to your `settings.json` file before running the tests from VS Code:
 
 ```
  "jestrunner.debugOptions": {
@@ -28,7 +30,7 @@ If you're using the Jest Runner extension in Visual Studio Code, you'll need to
   "jestrunner.jestCommand": "NODE_OPTIONS=--experimental-vm-modules node 'node_modules/jest/bin/jest.js'",
 ```
 
-You can run our tests either with the commands covered in the following sections or using the jest runnner extension directly from the IDE.
+You can run our tests either with the commands covered in the following sections or using the jest runner extension directly from the IDE.
 
 ### Unit Tests
 
@@ -39,15 +41,17 @@ You can run all unit tests by executing:
 $ pnpm test:unit
 ```
 
-To run unit tests for a specific package add the workspace name to the command. For the ai-api package this would be:
+To run unit tests for a specific package add the workspace name to the command. 
+For the ai-api package this would be:
 
 ```bash
 $ pnpm ai-api test
 ```
 
 ### Type Tests
 
-As this project is written in TypeScript, it will be consumable by other TypeScript projects. We use `tsd` to test that our resulting API meets our expectations.
+As this project is written in TypeScript, it will be consumable by other TypeScript projects. 
+We use `tsd` to test that our resulting API meets our expectations.
 The type tests are located at [`tests/type-tests`](./tests/type-tests).
 
 To run the type tests, execute:
@@ -62,11 +66,11 @@ The E2E tests are based on a locally running server providing a REST interface u
 This server is used by the E2E tests located at [tests/e2e-tests](./test-packages/e2e-tests).
 
 **Attention** The imports in the E2E tests use the root packages e.g. `@sap-ai-sdk/ai-api` to mimic the way a customer would use it.
-So if you made code changes in one of the packages you need to run `pnpm compile` to make the changes take effect.
+Thus, if you made code changes in one of the packages you need to run `pnpm compile` to make the changes take effect.
 
 Before running the E2E tests, ensure that you have a `.env` file located in `tests/e2e-tests` folder.
 
-Inside the `.env` file, define an `AICORE_SERVICE_KEY` variable and initialize it with the service binding of `aicore`. You can obtain this binding from the `VCAP_SERVICES` environment variable or from the service key defined in your BTP subaccount.
+Inside the `.env` file, define an `AICORE_SERVICE_KEY` variable and initialize it with the service binding of `aicore`. You can obtain this binding from the `VCAP_SERVICES` environment variable or from the service key defined in your SAP BTP subaccount.
 
 To run the tests, use the following command:
 
@@ -82,14 +86,48 @@ To fix all linting issues, run:
 $ pnpm lint:fix
 ```
 
+## Releases
+
+To release a new version, ensure that the following prerequisites are met:
+
+- The smoke tests are passing.
+- There are changesets under the `.changeset` directory. 
+  Without changesets, there should be nothing to release.
+
+If this is the case, follow these steps:
+
+1. **Bump the version**: Execute the `bump` workflow from the `main` branch.
+   If you want to release a new major version, enter the full major version as a precaution.
+   Skip providing a version for minor and patch version releases.
+   This bumps the version on the `main` branch and creates a tag and draft release with release notes on GitHub.
+2. **Publish to npm**: Find the draft release in the [GitHub releases](https://github.com/SAP/ai-sdk-js/releases), check the release notes, and press **Publish release**. This triggers the `publish` workflow that publishes the new version to [`npmjs.com`](https://www.npmjs.com/settings/sap-ai-sdk/packages).
+
+Finally, check that everything is published as expected on npm.
+
+### How to Roll Back Releases
+
+Once a release is published on npm, you can no longer take it back.
+To fix issues in published packages, you need to publish a new version.
+
+If you find an issue with the release or something fails before publishing, you can revert the release.
+Make sure to:
+
+- Revert the bump commit.
+- Delete the draft release.
+- Delete the version tag.
+
+Then you can fix the error and try again from the state before the release.
+
 ## Contributing Code or Documentation
 
 You are welcome to contribute code in order to fix a bug or to implement a new feature that is logged as an issue.
 
 The following rules govern code contributions:
 
 - Contributions must be licensed under the [Apache 2.0 License](./LICENSE)
-- Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
+- Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) when they create the first pull request to this project. 
+  This happens in an automated fashion during the submission process. 
+  SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
 
 Also make sure to follow our [style guide](./STYLEGUIDE)
 

README.md

@@ -3,16 +3,18 @@
 
 # SAP Cloud SDK for AI
 
-Integrate chat completion into your business applications with SAP Cloud SDK for AI. Leverage the generative AI hub of [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core) to make use of templating, grounding, data masking, content filtering and more. Setup your SAP AI Core instance with SAP Cloud SDK for AI Core.
+Integrate chat completion into your business applications with SAP Cloud SDK for AI. 
+Leverage the generative AI hub of [SAP AI Core](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/what-is-sap-ai-core) to make use of templating, grounding, data masking, content filtering and more. 
+Setup your SAP AI Core instance with SAP Cloud SDK for AI Core.
 
 ### Table of Contents
 
 - [Requirements and Setup](#requirements-and-setup)
 - [Packages](#packages)
   - [@sap-ai-sdk/ai-api](#sap-ai-sdkai-api)
   - [@sap-ai-sdk/foundation-models](#sap-ai-sdkfoundation-models)
-  - [@sap-ai-sdk/orchestration](#sap-ai-sdkorchestration)
   - [@sap-ai-sdk/langchain](#sap-ai-sdklangchain)
+  - [@sap-ai-sdk/orchestration](#sap-ai-sdkorchestration)
 - [SAP Cloud SDK for AI Sample Project](#sap-cloud-sdk-for-ai-sample-project)
 - [Local Testing](#local-testing)
 - [Support, Feedback, Contribution](#support-feedback-contribution)
@@ -28,18 +30,6 @@ See the documentation of each individual package under the [Packages](#packages)
 
 This project publishes multiple packages and is managed using [pnpm](https://pnpm.io/)
 
-### @sap-ai-sdk/orchestration
-
-This package incorporates generative AI [orchestration](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/orchestration) capabilities into your AI activities in SAP AI Core and SAP AI Launchpad.
-
-#### Installation
-
-```
-$ npm install @sap-ai-sdk/orchestration
-```
-
-For details on orchestration client, refer to this [document](https://github.com/SAP/ai-sdk-js/blob/main/packages/orchestration/README.md).
-
 ### @sap-ai-sdk/ai-api
 
 This package provides tools to manage your scenarios and workflows in SAP AI Core.
@@ -81,9 +71,22 @@ $ npm install @sap-ai-sdk/langchain
 
 For details on LangChain model client, refer to this [document](https://github.com/SAP/ai-sdk-js/blob/main/packages/langchain/README.md).
 
+### @sap-ai-sdk/orchestration
+
+This package incorporates generative AI [orchestration](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/orchestration) capabilities into your AI activities in SAP AI Core and SAP AI Launchpad.
+
+#### Installation
+
+```
+$ npm install @sap-ai-sdk/orchestration
+```
+
+For details on orchestration client, refer to this [document](https://github.com/SAP/ai-sdk-js/blob/main/packages/orchestration/README.md).
+
 ## SAP Cloud SDK for AI Sample Project
 
-We have created a sample project demonstrating the different clients' usage of the SAP Cloud SDK for AI for TypeScript/JavaScript. The [project README](https://github.com/SAP/ai-sdk-js/blob/main/sample-code/README.md) outlines the set-up needed to build and run it locally.
+We have created a sample project demonstrating the different clients' usage of the SAP Cloud SDK for AI for TypeScript/JavaScript.
+The [project README](https://github.com/SAP/ai-sdk-js/blob/main/sample-code/README.md) outlines the set-up needed to build and run it locally.
 
 ## Local Testing
 
@@ -97,18 +100,23 @@ This setup enables local testing of clients such as orchestration and OpenAI, pr
 
 ## 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).
+This project is open to feature requests, bug reports and questions 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).
+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).
 
 ## Security / Disclosure
 
-If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/ai-sdk-js/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.
+If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/SAP/ai-sdk-js/security/policy) on how to report it.
+Please do not create GitHub issues for security-related doubts or problems.
 
 ## Code of Conduct
 
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone.
+By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/SAP/.github/blob/main/CODE_OF_CONDUCT.md) at all times.
 
 ## Licensing
 
-Copyright 2024 SAP SE or an SAP affiliate company and ai-sdk-js contributors. Please see our [LICENSE](LICENSE) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/ai-sdk-js).
+Copyright 2024 SAP SE or an SAP affiliate company and ai-sdk-js contributors.
+Please see our [LICENSE](LICENSE) for copyright and license information.
+Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://api.reuse.software/info/github.com/SAP/ai-sdk-js).

adr/001-esm.md

@@ -6,7 +6,8 @@ decided
 
 ## Context
 
-The JavaScript ecosystem is changing. Node.js projects have to decide whether to use the legacy CommonJS modules (CJS, `require`) or ECMAScript Modules (ESM, `import`).
+The JavaScript ecosystem is changing.
+Node.js projects have to decide whether to use the legacy CommonJS modules (CJS, `require`) or ECMAScript Modules (ESM, `import`).
 As ESM is not compatible with CJS, this is an important decision.
 This [article](https://blog.stackademic.com/commonjs-vs-ecmascript-modules-esm-choosing-the-right-module-system-for-your-javascript-project-ef4efa856554) describes the most relevant differences.
 Although ESM has been on the market since 2016, CJS is still widely used (I couldn't find any concrete numbers).
@@ -24,7 +25,7 @@ Due to the incompatibility between both module systems library developers hesita
 
 ### Pros
 
-We can carefully check the community's opinion by communicating ESM compatibility only and be a pull factor as long as there are no hard blocks for either bigger projects or a large number of projects.
+We can check the community's opinion by communicating ESM compatibility only and be a pull factor as long as there are no hard blocks for either bigger projects or a large number of projects.
 If it becomes a blocker, we can react without breaking changes.
 We can benefit from the performance improvements in ESM.
 
@@ -84,7 +85,7 @@ Pro:
 ### Evaluation from PoC
 
 Hybrid mode is in fact CJS.
-Generally it is possible to find workarounds to use ESM in CJS, but it gets ugly very quickly and has limitations:
+Generally it is possible to find workarounds to use ESM in CJS, but it gets ugly quickly and has limitations:
 
 - The lib cannot use top level awaits.
 - Typings get lost.

adr/002-project-structure.md

@@ -1,4 +1,4 @@
-# Project Structure of the SAP AI SDK for JS
+# Project Structure of the SAP Cloud SDK for AI (JavaScript / TypeScript)
 
 ## Modules
 
@@ -7,6 +7,6 @@
 - @sap-ai-sdk/ai-api
     - AI API generated client + types
 - @sap-ai-sdk/foundation-models
-    - Foundation model client for LLM Access (Azure Openai, ...)
+    - Foundation model client for LLM Access (Azure Openai, and more)
 - @sap-ai-sdk/orchestration
     - Orchestration generated client

adr/template.md

@@ -21,4 +21,4 @@ Often a list of options with pros and cons including the selection implementatio
 
 ## Option B
 
-...
+<!-- ... -->

docs/list-tested-APIs.md

@@ -1,28 +1,31 @@
 # Available APIs
 
-✅ Available and tested
+APIs marked with ✅ are tested.
 
-❗Warning: APIs not marked as tested are experimental. Use them at your own risk.
+❗Otherwise experimental!
+Use them at your own risk.
 
-# AI Core
+## AI API
 
-- ApplicationAPI
-- ArtifactApi ✅
-- ConfigurationApi ✅
-- DeploymentApi ✅
-- DockerRegistrySecretApi
-- ExecutableApi
-- ExecutionApi ✅
-- ExecutionScheduleApi
-- FileApi
-- KpiApi
-- MetaApi
-- MetricsApi
-- ObjectStoreSecretApi
-- RepositoryApi
-- ResourceApi
-- ResourceGroupApi
-- ResourceQuotaApi
-- ScenarioApi ✅
-- SecretApi
-- ServiceApi
+| API                     | Status |
+| ----------------------- | ------ |
+| ApplicationApi          |        |
+| ArtifactApi             | ✅     |
+| ConfigurationApi        | ✅     |
+| DeploymentApi           | ✅     |
+| DockerRegistrySecretApi |        |
+| ExecutableApi           |        |
+| ExecutionApi            | ✅     |
+| ExecutionScheduleApi    |        |
+| FileApi                 |        |
+| KpiApi                  |        |
+| MetaApi                 |        |
+| MetricsApi              |        |
+| ObjectStoreSecretApi    |        |
+| RepositoryApi           |        |
+| ResourceApi             |        |
+| ResourceGroupApi        |        |
+| ResourceQuotaApi        |        |
+| ScenarioApi             | ✅     |
+| SecretApi               |        |
+| ServiceApi              |        |