chore: Follow-up Documentation cleanup (#159)

* chore: add local testing instructions * fix: Changes from lint * chore: minor sentence fix * chore: fix sentence * chore: add missing sections * Update packages/orchestration/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * Update packages/orchestration/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * Update packages/orchestration/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * Update packages/orchestration/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * Update packages/langchain/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * Update packages/ai-api/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * chore: link client readmes in root * Update packages/orchestration/README.md Co-authored-by: Marika Marszalkowski <[email protected]> * chore: Address review comments * chore: address review comments * fix: Changes from lint * chore: address review comments * chore: add deploymentID relationship * chore: address review comment * chore: address review comments * chore: remove usage of you * chore: remove usages of you. * fix: Changes from lint * chore: remove more usages of you * chore: address review comment * chore: minor cleanup * Update packages/orchestration/README.md Co-authored-by: Deeksha Sinha <[email protected]> * Update packages/orchestration/README.md Co-authored-by: Deeksha Sinha <[email protected]> * Update packages/orchestration/README.md Co-authored-by: Deeksha Sinha <[email protected]> * chore: cleanup links * chore: cleanup links * chore: explain deployment id * chore: explain deployment ID * chore: fix toc * Update packages/orchestration/README.md Co-authored-by: Deeksha Sinha <[email protected]> * Update packages/orchestration/README.md Co-authored-by: Deeksha Sinha <[email protected]> * chore: address review comments * chore: final review comment * chore: address review comments * fix: Changes from lint * chore: remove requestConfig section * chore: cleanup convenience functions usage * chore: fix toc * chore: fix toc * Update README.md Co-authored-by: Zhongpin Wang <[email protected]> * Apply suggestions from code review Co-authored-by: Zhongpin Wang <[email protected]> * Apply suggestions from code review * Update packages/orchestration/README.md * Update packages/orchestration/README.md * Update packages/orchestration/README.md * Apply suggestions from code review * fix: Changes from lint --------- Co-authored-by: cloud-sdk-js <[email protected]> Co-authored-by: Marika Marszalkowski <[email protected]> Co-authored-by: Deeksha Sinha <[email protected]> Co-authored-by: Zhongpin Wang <[email protected]>
SAP · Oct 4, 2024 · 863af52 · 863af52
1 parent 8ba44f1
commit 863af52
Show file tree

Hide file tree

Showing 5 changed files with 169 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@ Integrate chat completion into your business applications with SAP Cloud SDK for
   - [@sap-ai-sdk/orchestration](#sap-ai-sdkorchestration)
   - [@sap-ai-sdk/langchain](#sap-ai-sdklangchain)
 - [SAP Cloud SDK for AI Sample Project](#sap-cloud-sdk-for-ai-sample-project)
+- [Local Testing](#local-testing)
 - [Support, Feedback, Contribution](#support-feedback-contribution)
 - [Security / Disclosure](#security--disclosure)
 - [Code of Conduct](#code-of-conduct)
@@ -32,6 +33,8 @@ This package incorporates generative AI [orchestration](https://help.sap.com/doc
 $ 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.
@@ -47,6 +50,8 @@ This package provides tools to manage your scenarios and workflows in SAP AI Cor
 $ npm install @sap-ai-sdk/ai-api
 ```
 
+For details on the client, refer to this [document](https://github.com/SAP/ai-sdk-js/blob/main/packages/ai-api/README.md).
+
 ### @sap-ai-sdk/foundation-models
 
 This package incorporates generative AI foundation models into your AI activities in SAP AI Core and SAP AI Launchpad.
@@ -57,6 +62,8 @@ This package incorporates generative AI foundation models into your AI activitie
 $ npm install @sap-ai-sdk/foundation-models
 ```
 
+For details on foundation model clients, refer to this [document](https://github.com/SAP/ai-sdk-js/blob/main/packages/foundation-models/README.md).
+
 ### @sap-ai-sdk/langchain
 
 This package provides LangChain model clients, built on top of the foundation model clients of the SAP Cloud SDK for AI.
@@ -67,15 +74,27 @@ This package provides LangChain model clients, built on top of the foundation mo
 $ 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 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](./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
+
+To test SAP Cloud SDK for AI features locally during application development, follow these steps:
+
+- Download a service key for the AI Core service instance.
+- Set the downloaded service key as the `AICORE_SERVICE_KEY` environment variable in the local environment.
+
+The SDK parses the service key from the environment variable to interact with the AI Core service.
+This setup enables local testing of clients such as orchestration and OpenAI, provided that deployments for orchestration and OpenAI exist in SAP BTP.
 
 ## 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](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
 

diff --git a/packages/ai-api/README.md b/packages/ai-api/README.md
@@ -11,15 +11,17 @@ We maintain a list of [currently available and tested AI Core APIs](https://gith
 
 ## Table of Contents
 
-1. [Installation](#installation)
-2. [Prerequisites](#prerequisites)
-3. [Usage](#usage)
-   - [Create an Artifact](#create-an-artifact)
-   - [Create a Configuration](#create-a-configuration)
-   - [Create a Deployment](#create-a-deployment)
-   - [Delete a Deployment](#delete-a-deployment)
-4. [Support, Feedback, Contribution](#support-feedback-contribution)
-5. [License](#license)
+- [Installation](#installation)
+- [Version Management](#version-management)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+  - [Create an Artifact](#create-an-artifact)
+  - [Create a Configuration](#create-a-configuration)
+  - [Create a Deployment](#create-a-deployment)
+  - [Delete a Deployment](#delete-a-deployment)
+- [Local Testing](#local-testing)
+- [Support, Feedback, Contribution](#support-feedback-contribution)
+- [License](#license)
 
 ## Installation
 
@@ -169,6 +171,10 @@ async function modifyDeployment() {
 }
 ```
 
+## Local Testing
+
+For local testing instructions, refer to this [section](https://github.com/SAP/ai-sdk-js/blob/main/README.md#local-testing).
+
 ## 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).

diff --git a/packages/foundation-models/README.md b/packages/foundation-models/README.md
@@ -4,14 +4,15 @@ This package incorporates generative AI foundation models into your AI activitie
 
 ## Table of Contents
 
-- [Table of Contents](#table-of-contents)
 - [Installation](#installation)
 - [Prerequisites](#prerequisites)
+- [Relationship between Models and Deployment ID](#relationship-between-models-and-deployment-id)
 - [Usage](#usage)
   - [Client Initialization](#client-initialization)
   - [Chat Client](#chat-client)
   - [Embedding Client](#embedding-client)
   - [Custom Request Configuration](#custom-request-configuration)
+- [Local Testing](#local-testing)
 - [Support, Feedback, Contribution](#support-feedback-contribution)
 - [License](#license)
 
@@ -26,9 +27,21 @@ $ npm install @sap-ai-sdk/foundation-models
 - [Enable the AI Core service in BTP](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/initial-setup).
 - Project configured with Node.js v20 or higher and native ESM support enabled.
 - A deployed OpenAI model in SAP Generative AI hub.
-  - Use the [`DeploymentApi`](../ai-api/README.md#deploymentapi) from `@sap-ai-sdk/ai-api` to deploy a model to SAP generative AI hub. For more information, see [here](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-deployment-for-generative-ai-model-in-sap-ai-core).
+  - Use the [`DeploymentApi`](https://github.com/SAP/ai-sdk-js/blob/main/packages/ai-api/README.md#create-a-deployment) from `@sap-ai-sdk/ai-api` to deploy a model to SAP generative AI hub.
+    For more information, see [here](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-deployment-for-generative-ai-model-in-sap-ai-core).
     Deployment can be set up for each model and model version, as well as a resource group intended for use with the generative AI hub.
-  - Once a deployment is complete, the model can be accessed via the `deploymentUrl`
+  - Once a deployment is complete, the model can be accessed via the `deploymentUrl`.
+
+## Relationship between Models and Deployment ID
+
+SAP AI Core manages access to generative AI models through the global AI scenario `foundation-models`.
+Creating a deployment for a model requires access to this scenario.
+
+Each model, model version, and resource group allows for a one-time deployment.
+After deployment completion, the response includes a `deploymentUrl` and an `id`, which is the deployment ID. For more information, see [here](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-deployment-for-generative-ai-model-in-sap-ai-core).
+[Resource groups](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/resource-groups?q=resource+group) represent a virtual collection of related resources within the scope of one SAP AI Core tenant.
+
+Consequently, each deployment ID and resource group uniquely map to a combination of model and model version within the `foundation-models` scenario.
 
 ## Usage
 
@@ -50,8 +63,6 @@ const chatClient = new AzureOpenAiChatClient({ modelName: 'gpt-4o' });
 const embeddingClient = new AzureOpenAiEmbeddingClient({ modelName: 'gpt-4o' });
 ```
 
-[Resource groups](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/resource-groups?q=resource+group) represent a virtual collection of related resources within the scope of one SAP AI Core tenant.
-
 The deployment ID and resource group can be used as an alternative to the model name for obtaining a model.
 
 ```ts
@@ -161,6 +172,10 @@ const response = await client.run(
 );
 ```
 
+## Local Testing
+
+For local testing instructions, refer to this [section](https://github.com/SAP/ai-sdk-js/blob/main/README.md#local-testing).
+
 ## 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).

diff --git a/packages/langchain/README.md b/packages/langchain/README.md
@@ -4,14 +4,16 @@ This package provides LangChain model clients built on top of the foundation mod
 
 ## Table of Contents
 
-1. [Installation](#installation)
-2. [Prerequisites](#prerequisites)
-3. [Usage](#usage)
-   - [Client Initialization](#client-initialization)
-   - [Chat Client](#chat-client)
-   - [Embedding Client](#embedding-client)
-4. [Support, Feedback, Contribution](#support-feedback-contribution)
-5. [License](#license)
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Relationship between Models and Deployment ID](#relationship-between-models-and-deployment-id)
+- [Usage](#usage)
+  - [Client Initialization](#client-initialization)
+  - [Chat Client](#chat-client)
+  - [Embedding Client](#embedding-client)
+- [Local Testing](#local-testing)
+- [Support, Feedback, Contribution](#support-feedback-contribution)
+- [License](#license)
 
 ## Installation
 
@@ -24,10 +26,22 @@ $ npm install @sap-ai-sdk/langchain
 - [Enable the AI Core service in SAP 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 root of your directory.
-  - Add an entry `AICORE_SERVICE_KEY='<content-of-service-key>'`.
+- A deployed model is available in SAP Generative AI hub.
+  - Use the [`DeploymentApi`](https://github.com/SAP/ai-sdk-js/blob/main/packages/ai-api/README.md#create-a-deployment) from `@sap-ai-sdk/ai-api` to deploy a model to SAP generative AI hub.
+    For more information, see [here](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-deployment-for-generative-ai-model-in-sap-ai-core).
+  - Once a deployment is complete, the model can be accessed via the `deploymentUrl`.
+
+## Relationship between Models and Deployment ID
+
+SAP AI Core manages access to generative AI models through the global AI scenario `foundation-models`.
+Creating a deployment for a model requires access to this scenario.
+
+Each model, model version, and resource group allows for a one-time deployment.
+After deployment completion, the response includes a `deploymentUrl` and an `id`, which is the deployment ID. For more information, see [here](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-deployment-for-generative-ai-model-in-sap-ai-core).
+
+[Resource groups](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/resource-groups?q=resource+group) represent a virtual collection of related resources within the scope of one SAP AI Core tenant.
+
+Consequently, each deployment ID and resource group uniquely map to a combination of model and model version within the `foundation-models` scenario.
 
 ## Usage
 
@@ -60,6 +74,9 @@ const chatClient = new AzureOpenAiChatClient({
 });
 ```
 
+**Do not pass a `deployment ID` to initialize the client.**
+For the LangChain model clients, initialization is done using the model name, model version and resource group.
+
 An important note is that LangChain clients by default attempt 6 retries with exponential backoff in case of a failure.
 Especially in testing environments you might want to reduce this number to speed up the process:
 
@@ -155,6 +172,10 @@ const vectorStore = await MemoryVectorStore.fromDocuments(
 const retriever = vectorStore.asRetriever();
 ```
 
+## Local Testing
+
+For local testing instructions, refer to this [section](https://github.com/SAP/ai-sdk-js/blob/main/README.md#local-testing).
+
 ## 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).