diff --git a/docs/docs/learn/003-adapters/004-bedrock/001-overview.mdx b/docs/docs/learn/003-adapters/004-bedrock/001-overview.mdx new file mode 100644 index 00000000..654668d8 --- /dev/null +++ b/docs/docs/learn/003-adapters/004-bedrock/001-overview.mdx @@ -0,0 +1,29 @@ +--- +sidebar_label: "Overview" +--- + +import { CodeEditor } from "@site/src/components/CodeEditor/CodeEditor"; +import exampleUrlFileAiChatBot from "./examples/aiAssistant-default"; + +# Bedrock Adapter + +`NLUX` offers integration with Bedrock SDK API. + +## About Bedrock + +Bedrock is a versatile framework designed for creating, configuring, and managing AI-driven chat applications. It provides a robust set of tools and features to streamline the integration of AI models, handle data transfer efficiently, and customize inference configurations. This documentation provides an overview of Bedrock's key components and their functionalities. + +## Supported Features + +The `NLUX` LangServe adapter can do the following: + +- Offers a way to **send a user prompt to a Bedrock API**. +- **Handles the API responses** and displays them in the chat UI (single responses and streamed text). + +If you have specific requirements that are not covered by the adapter, please submit a feature request +[here](https://github.com/nlkitai/nlux/discussions) and we will consider adding it to the roadmap +if enough users request it. + +## Example: Bedrock Adapter With Default Settings + +Coming Soon. \ No newline at end of file diff --git a/docs/docs/learn/003-adapters/004-bedrock/_category_.json b/docs/docs/learn/003-adapters/004-bedrock/_category_.json new file mode 100644 index 00000000..bc49846b --- /dev/null +++ b/docs/docs/learn/003-adapters/004-bedrock/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Bedrock Adapter", + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "slug": "/learn/adapters/bedrock" + } +} diff --git a/docs/docs/learn/003-adapters/004-bedrock/examples/aiAssistant-batch.tsx b/docs/docs/learn/003-adapters/004-bedrock/examples/aiAssistant-batch.tsx new file mode 100644 index 00000000..141b7a96 --- /dev/null +++ b/docs/docs/learn/003-adapters/004-bedrock/examples/aiAssistant-batch.tsx @@ -0,0 +1,32 @@ +export default `import {AiChat} from '@nlux/react'; +import {useChatAdapter} from '@nlux/langchain-react'; +import '@nlux/themes/nova.css'; + +export default () => { + // LangServe adapter that connects to a demo LangChain Runnable API + const adapter = useChatAdapter({ + url: 'https://pynlux.api.nlkit.com/pirate-speak', + dataTransferMode: 'batch' + }); + + return ( + + ); +};`; diff --git a/docs/docs/learn/003-adapters/004-bedrock/examples/aiAssistant-default.tsx b/docs/docs/learn/003-adapters/004-bedrock/examples/aiAssistant-default.tsx new file mode 100644 index 00000000..27a1599c --- /dev/null +++ b/docs/docs/learn/003-adapters/004-bedrock/examples/aiAssistant-default.tsx @@ -0,0 +1,31 @@ +export default `import {AiChat} from '@nlux/react'; +import {useChatAdapter} from '@nlux/langchain-react'; +import '@nlux/themes/nova.css'; + +export default () => { + // LangServe adapter that connects to a demo LangChain Runnable API + const adapter = useChatAdapter({ + url: 'https://pynlux.api.nlkit.com/pirate-speak' + }); + + return ( + + ); +};`; diff --git a/docs/docs/learn/003-adapters/004-custom-adapters/001-create-custom-adapter.mdx b/docs/docs/learn/003-adapters/005-custom-adapters/001-create-custom-adapter.mdx similarity index 100% rename from docs/docs/learn/003-adapters/004-custom-adapters/001-create-custom-adapter.mdx rename to docs/docs/learn/003-adapters/005-custom-adapters/001-create-custom-adapter.mdx diff --git a/docs/docs/learn/003-adapters/004-custom-adapters/002-error-handling.md b/docs/docs/learn/003-adapters/005-custom-adapters/002-error-handling.md similarity index 100% rename from docs/docs/learn/003-adapters/004-custom-adapters/002-error-handling.md rename to docs/docs/learn/003-adapters/005-custom-adapters/002-error-handling.md diff --git a/docs/docs/learn/003-adapters/004-custom-adapters/_category_.json b/docs/docs/learn/003-adapters/005-custom-adapters/_category_.json similarity index 100% rename from docs/docs/learn/003-adapters/004-custom-adapters/_category_.json rename to docs/docs/learn/003-adapters/005-custom-adapters/_category_.json diff --git a/docs/docs/learn/003-adapters/004-custom-adapters/_custom-adapter-example/#js.mdx b/docs/docs/learn/003-adapters/005-custom-adapters/_custom-adapter-example/#js.mdx similarity index 100% rename from docs/docs/learn/003-adapters/004-custom-adapters/_custom-adapter-example/#js.mdx rename to docs/docs/learn/003-adapters/005-custom-adapters/_custom-adapter-example/#js.mdx diff --git a/docs/docs/learn/003-adapters/004-custom-adapters/_custom-adapter-example/#react.mdx b/docs/docs/learn/003-adapters/005-custom-adapters/_custom-adapter-example/#react.mdx similarity index 100% rename from docs/docs/learn/003-adapters/004-custom-adapters/_custom-adapter-example/#react.mdx rename to docs/docs/learn/003-adapters/005-custom-adapters/_custom-adapter-example/#react.mdx diff --git a/docs/docs/learn/003-adapters/004-custom-adapters/error-message-and-logs.png b/docs/docs/learn/003-adapters/005-custom-adapters/error-message-and-logs.png similarity index 100% rename from docs/docs/learn/003-adapters/004-custom-adapters/error-message-and-logs.png rename to docs/docs/learn/003-adapters/005-custom-adapters/error-message-and-logs.png diff --git a/packages/js/bedrock/src/bedrock/builder/builder.ts b/packages/js/bedrock/src/bedrock/builder/builder.ts index f14c835c..16c7d5a2 100644 --- a/packages/js/bedrock/src/bedrock/builder/builder.ts +++ b/packages/js/bedrock/src/bedrock/builder/builder.ts @@ -1,69 +1,102 @@ -import {BedrockRuntimeClientConfigType, InferenceConfiguration} from '@aws-sdk/client-bedrock-runtime'; -import {ChatAdapterBuilder as CoreChatAdapterBuilder, DataTransferMode, StandardChatAdapter} from '@nlux/core'; +import { + BedrockRuntimeClientConfigType, + InferenceConfiguration, +} from "@aws-sdk/client-bedrock-runtime"; +import { + ChatAdapterBuilder as CoreChatAdapterBuilder, + DataTransferMode, + StandardChatAdapter, +} from "@nlux/core"; export interface ChatAdapterBuilder - extends CoreChatAdapterBuilder { - /** - * Create a new Bedrock Inference API adapter. - * Adapter users don't need to call this method directly. It will be called by nlux when the adapter is expected - * to be created. - * - * @returns {StandardChatAdapter} - */ - create(): StandardChatAdapter; + extends CoreChatAdapterBuilder { + /** + * Create a new Bedrock Inference API adapter. + * Adapter users don't need to call this method directly. It will be called by nlux when the adapter is expected + * to be created. + * + * @returns {StandardChatAdapter} + */ + create(): StandardChatAdapter; - /** - * The authorization token to use for Bedrock Inference API. - * This will be passed to the `Authorization` header of the HTTP request. - * If no token is provided, the request will be sent without an `Authorization` header as in this example: - * `"Authorization": f"Bearer {AUTH_TOKEN}"`. - * - * Public models do not require an authorization token, but if your model is private, you will need to provide one. - * - * @optional - * @param {string} cred - * @returns {ChatAdapterBuilder} - */ - withCredintial( - cred: BedrockRuntimeClientConfigType['credentials'], - ): ChatAdapterBuilder; + /** + * The authorization token to use for Bedrock Inference API. + * This will be passed to the `Authorization` header of the HTTP request. + * If no token is provided, the request will be sent without an `Authorization` header as in this example: + * `"Authorization": f"Bearer {AUTH_TOKEN}"`. + * + * Public models do not require an authorization token, but if your model is private, you will need to provide one. + * + * @optional + * @param {string} cred + * @returns {ChatAdapterBuilder} + */ + withCredintial( + cred: BedrockRuntimeClientConfigType["credentials"] + ): ChatAdapterBuilder; - /** - * Instruct the adapter to connect to API and load data either in streaming mode or in batch mode. - * The `stream` mode would use protocols such as websockets or server-side events, and nlux will display data as - * it's being generated by the server. The `batch` mode would use a single request to fetch data, and the response - * would only be displayed once the entire message is loaded. - * - * @optional - * @default 'stream' - * @returns {ChatAdapterBuilder} - */ - withDataTransferMode(mode: DataTransferMode): ChatAdapterBuilder; - /** - * Inference parameters to pass to the model. Converse supports a base - * set of inference parameters. If you need to pass additional parameters that the model - * supports, use the additionalModelRequestFields request field. - * - * @param {InferenceConfiguration} inferenceConfig - * @returns {ChatAdapterBuilder} - */ - withInferenceConfig( - inferenceConfig: InferenceConfiguration, - ): ChatAdapterBuilder; - /** - * The model or the endpoint to use for Bedrock Inference API. - * You should provide either a model or an endpoint, but not both. - * - * @param {string} model - * @returns {ChatAdapterBuilder} - */ - withModel(model: string): ChatAdapterBuilder; - /** - * The endpoint to use for Bedrock Inference API. - * - * @optional - * @param {string} region - * @returns {ChatAdapterBuilder} - */ - withRegion(region: string): ChatAdapterBuilder; + /** + * Instruct the adapter to connect to API and load data either in streaming mode or in batch mode. + * The `stream` mode would use protocols such as websockets or server-side events, and nlux will display data as + * it's being generated by the server. The `batch` mode would use a single request to fetch data, and the response + * would only be displayed once the entire message is loaded. + * + * @optional + * @default 'stream' + * @returns {ChatAdapterBuilder} + */ + withDataTransferMode(mode: DataTransferMode): ChatAdapterBuilder; + /** + * Inference parameters to pass to the model. Converse supports a base + * set of inference parameters. If you need to pass additional parameters that the model + * supports, use the additionalModelRequestFields request field. + * + * @param {InferenceConfiguration} inferenceConfig + * @returns {ChatAdapterBuilder} + */ + withInferenceConfig( + inferenceConfig: InferenceConfiguration + ): ChatAdapterBuilder; + /** + * The model or the endpoint to use for Bedrock Inference API. + * You should provide either a model or an endpoint, but not both. + * + * @param {string} model + * @returns {ChatAdapterBuilder} + */ + withModel(model: string): ChatAdapterBuilder; + /** + * The region to use for Bedrock Inference API. + * + * @optional + * @param {string} region + * @returns {ChatAdapterBuilder} + */ + withRegion(region: string): ChatAdapterBuilder; + /** + * The endpoint to use for Bedrock Inference API. + * + * @optional + * @param {string} endpoint + * @returns {ChatAdapterBuilder} + */ + withEndpoint(endpoint: string): ChatAdapterBuilder; + + /** + * The max number of attempts for retrying Bedrock Inference API. + * + * @optional + * @param {number} maxAttempts + * @returns {ChatAdapterBuilder} + */ + withMaxAttempts(maxAttempts: number): ChatAdapterBuilder; + + /** + * Unique Service Identifier. + * + * @optional + * @param {number} serviceId + * @returns {ChatAdapterBuilder} + */ + withServiceId(serviceId: string): ChatAdapterBuilder; } diff --git a/packages/js/bedrock/src/bedrock/builder/builderImpl.ts b/packages/js/bedrock/src/bedrock/builder/builderImpl.ts index 8460b32c..b6cb40dc 100644 --- a/packages/js/bedrock/src/bedrock/builder/builderImpl.ts +++ b/packages/js/bedrock/src/bedrock/builder/builderImpl.ts @@ -1,102 +1,144 @@ -import {BedrockRuntimeClientConfigType, InferenceConfiguration} from '@aws-sdk/client-bedrock-runtime'; -import {DataTransferMode} from '@nlux/core'; -import {NluxUsageError, NluxValidationError} from '@shared/types/error'; -import {BedrockChatAdapterImpl} from '../adapter/chatAdapter'; -import {ChatAdapterBuilder} from './builder'; +import { + BedrockRuntimeClientConfigType, + InferenceConfiguration, +} from "@aws-sdk/client-bedrock-runtime"; +import { DataTransferMode } from "@nlux/core"; +import { NluxUsageError, NluxValidationError } from "@shared/types/error"; +import { BedrockChatAdapterImpl } from "../adapter/chatAdapter"; +import { ChatAdapterBuilder } from "./builder"; export class ChatAdapterBuilderImpl - implements ChatAdapterBuilder { - private credentials: BedrockRuntimeClientConfigType['credentials'] | null = - null; - private inferenceConfig: InferenceConfiguration | null = null; - private region: string | null = null; - private theDataTransferMode: DataTransferMode = 'stream'; - private theModel: string | null = null; - private withDataTransferModeCalled = false; + implements ChatAdapterBuilder +{ + private credentials: BedrockRuntimeClientConfigType["credentials"] | null = + null; + private inferenceConfig: InferenceConfiguration | null = null; + private region: string | null = null; + private endpoint: string | null = null; + private theDataTransferMode: DataTransferMode = "stream"; + private theModel: string | null = null; + private serviceId: string | null = null; + private maxAttempts: number | null = null; + private withDataTransferModeCalled = false; - create(): BedrockChatAdapterImpl { - if (!this.theModel) { - throw new NluxValidationError({ - source: this.constructor.name, - message: - 'You must provide a model or an endpoint using the "withModel()" method or the ' + - '"withEndpoint()" method!', - }); - } + create(): BedrockChatAdapterImpl { + if (!this.theModel) { + throw new NluxValidationError({ + source: this.constructor.name, + message: + 'You must provide a model or an endpoint using the "withModel()" method or the ' + + '"withEndpoint()" method!', + }); + } - return new BedrockChatAdapterImpl({ - dataTransferMode: this.theDataTransferMode, - model: this.theModel ?? undefined, - credentials: this.credentials ?? undefined, - region: this.region ?? undefined, + return new BedrockChatAdapterImpl({ + dataTransferMode: this.theDataTransferMode, + model: this.theModel ?? undefined, + credentials: this.credentials ?? undefined, + region: this.region ?? undefined, + inferenceConfig: this.inferenceConfig ?? undefined, + endpoint: this.endpoint ?? undefined, + maxAttempts: this.maxAttempts ?? undefined, + serviceId: this.serviceId ?? undefined, + }); + } - inferenceConfig: this.inferenceConfig ?? undefined, - }); + withCredintial( + cred: BedrockRuntimeClientConfigType["credentials"] + ): ChatAdapterBuilder { + if (this.credentials !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: "Cannot set the cred token more than once", + }); } - withCredintial( - cred: BedrockRuntimeClientConfigType['credentials'], - ): ChatAdapterBuilder { - if (this.credentials !== null) { - throw new NluxUsageError({ - source: this.constructor.name, - message: 'Cannot set the cred token more than once', - }); - } + this.credentials = cred; + return this; + } - this.credentials = cred; - return this; + withDataTransferMode(mode: DataTransferMode): ChatAdapterBuilder { + if (this.withDataTransferModeCalled) { + throw new NluxUsageError({ + source: this.constructor.name, + message: "Cannot set the data loading mode more than once", + }); } - withDataTransferMode(mode: DataTransferMode): ChatAdapterBuilder { - if (this.withDataTransferModeCalled) { - throw new NluxUsageError({ - source: this.constructor.name, - message: 'Cannot set the data loading mode more than once', - }); - } + this.theDataTransferMode = mode; + this.withDataTransferModeCalled = true; + return this; + } - this.theDataTransferMode = mode; - this.withDataTransferModeCalled = true; - return this; + withInferenceConfig( + inferenceConfig: InferenceConfiguration + ): ChatAdapterBuilder { + if (this.inferenceConfig !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: "Cannot set the Inference Config more than once", + }); } + this.inferenceConfig = inferenceConfig; + return this; + } - withInferenceConfig( - inferenceConfig: InferenceConfiguration, - ): ChatAdapterBuilder { - if (this.inferenceConfig !== null) { - throw new NluxUsageError({ - source: this.constructor.name, - message: 'Cannot set the Inference Config more than once', - }); - } - this.inferenceConfig = inferenceConfig; - return this; + withModel(model: string) { + if (this.theModel !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: + "Cannot set the model because a model or an endpoint has already been set", + }); } - withModel(model: string) { - if (this.theModel !== null) { - throw new NluxUsageError({ - source: this.constructor.name, - message: - 'Cannot set the model because a model or an endpoint has already been set', - }); - } + this.theModel = model; + return this; + } + + withRegion(region: string): ChatAdapterBuilder { + if (this.region !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: "Cannot set the region because an region has already been set", + }); + } - this.theModel = model; - return this; + this.region = region; + return this; + } + withEndpoint(endpoint: string): ChatAdapterBuilder { + if (this.endpoint !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: + "Cannot set the endpoint because endpoint has already been set", + }); } - withRegion(region: string): ChatAdapterBuilder { - if (this.region !== null) { - throw new NluxUsageError({ - source: this.constructor.name, - message: - 'Cannot set the endpoint because a model or an endpoint has already been set', - }); - } + this.endpoint = endpoint; - this.region = region; - return this; + return this; + } + + withMaxAttempts(maxAttempts: number): ChatAdapterBuilder { + if (this.maxAttempts !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: "Cannot set the max attempts because it has already been set", + }); + } + this.maxAttempts = maxAttempts; + return this; + } + withServiceId(serviceId: string): ChatAdapterBuilder { + if (this.serviceId !== null) { + throw new NluxUsageError({ + source: this.constructor.name, + message: "Cannot set the serviceId because it has already been set", + }); } + this.serviceId = serviceId; + return this; + } }