diff --git a/components/config-tables/config-table.tsx b/components/config-tables/config-table.tsx new file mode 100644 index 0000000..2e27f40 --- /dev/null +++ b/components/config-tables/config-table.tsx @@ -0,0 +1,49 @@ +export const ConfigTable = ({ + columns, + data, +}: { + columns: { key: string; title: string }[]; + data: { [key: string]: string }[]; +}) => { + return ( + + + + {columns.map((column) => ( + + ))} + + + + {data.map((row, index) => ( + + {columns.map((column) => ( + + ))} + + ))} + +
+ {column.title} +
+ {column.key === "accepted_values" && row.av_as_code ? ( + row[column.key].split(",").map((value, index) => ( + + {value.trim()} + + )) + ) : column.key === "property" ? ( + + {row[column.key]} + + ) : ( +
{row[column.key]}
+ )} +
+ ); +}; + +ConfigTable.displayName = "ConfigTable"; diff --git a/components/config-tables/model-config-table.tsx b/components/config-tables/model-config-table.tsx new file mode 100644 index 0000000..b0d0e06 --- /dev/null +++ b/components/config-tables/model-config-table.tsx @@ -0,0 +1,73 @@ +import { ConfigTable } from "./config-table"; + +export const ModelConfigTable = () => { + const columns = [ + { key: "property", title: "Property" }, + { key: "accepted_values", title: "Accepted Values" }, + { key: "description", title: "Description" }, + ]; + const data = [ + { + property: "name", + accepted_values: "gpt4o, gemini15flash", + av_as_code: "true", + description: + "Name of the LLM model to use for the chat agent. If not provided, the default model for the agent type will be used.", + }, + { + property: "version", + accepted_values: "Depends on the model being used", + description: + "Version of the LLM model to use for the chat agent. If not provided, the latest version of the model will be used.", + }, + { + property: "temperature", + accepted_values: "0.0 to 1.0", + description: + "Controls the randomness of the output. A higher value will result in more diverse responses.", + }, + { + property: "maxOutputTokens", + accepted_values: "Depends on the model being used", + description: "Maximum number of tokens to generate.", + }, + { + property: "stopSequences", + accepted_values: "Array of strings", + description: "Sequences to stop generation at.", + }, + { + property: "safetySettings", + accepted_values: "Object", + description: "Safety settings for the model.", + }, + { + property: "size", + accepted_values: "1024x1024, 1792x1024, 1024x1792", + av_as_code: "true", + description: "Size of the output image. Supported only by DALL-E models.", + }, + { + property: "style", + accepted_values: "vivid, natural", + av_as_code: "true", + description: + "Style of the output image. Supported only by DALL-E models.", + }, + { + property: "quality", + accepted_values: "preview, full", + av_as_code: "true", + description: + "Quality of the output image. Supported only by DALL-E models.", + }, + { + property: "response_format", + accepted_values: "b64_json, url", + av_as_code: "true", + description: "Format of the response. Supported only by DALL-E models.", + }, + ]; + + return ; +}; diff --git a/components/config-tables/rag-config-table.tsx b/components/config-tables/rag-config-table.tsx new file mode 100644 index 0000000..b5d9dd8 --- /dev/null +++ b/components/config-tables/rag-config-table.tsx @@ -0,0 +1,37 @@ +import { ConfigTable } from "./config-table"; + +export const RAGConfigTable = () => { + const columns = [ + { key: "property", title: "Property" }, + { key: "accepted_values", title: "Accepted Values" }, + { key: "description", title: "Description" }, + ]; + const data = [ + { + property: "topic", + accepted_values: "String", + description: + "Topic for RAG chat agent. Required if RAG is enabled. Queries are restricted to be relevant to the given topic so to prevent unintended use.", + }, + { + property: "enableRAG", + accepted_values: "Boolean", + description: + "Enable RAG (Retrieval Augmented Generation) functionality for this endpoint. Must provide either a retriever method or the retriever configurations if set to true.", + }, + { + property: "retriever", + accepted_values: "Function", + description: + "Method to retrieve documents for RAG. Can be obtained from the `getDataRetriever` method.", + }, + { + property: "retrieverConfig", + accepted_values: "Object", + description: + "Configuration for the RAG retriever, for example, number of documents to retrieve, algorithm to use, etc.", + }, + ]; + + return ; +}; diff --git a/pages/chat-endpoints/chat-endpoint-configurations.mdx b/pages/chat-endpoints/chat-endpoint-configurations.mdx index 38e0865..018f35e 100644 --- a/pages/chat-endpoints/chat-endpoint-configurations.mdx +++ b/pages/chat-endpoints/chat-endpoint-configurations.mdx @@ -1,53 +1,79 @@ import { Notice } from "../../components/notice"; +import { ModelConfigTable } from "../../components/config-tables/model-config-table"; +import { RAGConfigTable } from "../../components/config-tables/rag-config-table"; # Chat Endpoint Configurations -You can configure a chat endpoint with various features such as chat history, response caching, and API key authentication, by simply modifying the configurations provided to the `defineChatEndpoint` function. To use this, first import the method as following: - -```typescript copy -import { defineChatEndpoint } from "@oconva/qvikchat/endpoints"; -``` +One of the most powerful features of the QvikChat framework is the flexibility and efficiency it provides in configuring chat endpoints. From chat history, response caching, and RAG to authentication, you can configure a chat endpoint with various features by simply specifying the configurations for the endpoint. QvikChat provides all the underlying architecture to support these advanced features, so you can focus on building the chat service you need. ## Configurations Below are some of the chat endpoint configurations you can define. - `endpoint`: Server endpoint to which queries should be sent to run this chat flow. -- `chatAgentConfig`: Configurations for the chat agent, like LLM model, system prompt, chat prompt, and tools. [Read more](#chat-agent-config). -- `verbose`: If set to `true`, returns additional information in the response. May include usage information (like the number of input and output tokens used, input and output characters, etc.), tools calls information, and request details. By default, it is set to `false`. [Read more](#verbose-mode). -- `responseType`: Type of response that the endpoint should return. Can be `text`, `json`, or `media`. By default, it is set to `text`. [Read more](#response-type). -**Close-ended Chat Configurations** +### LLM Model Configurations + +- `modelConfig`: Configuration for the LLM model. This can include parameters like model name, model version, temperature, max output tokens, and safety settings. + +
+ View All Model Configurations + +
+ +### Prompts + +System prompt is used to configure the behavior, tone, and various other characteristics of the Large Language Model (LLM) model, before response generation. A well-structured system prompt designed with security and safety in mind can not only help generate high quality responses, it will also enable mitigation of LLM hallucinations and deterrence of malicious usage attempts (e.g., prompt injection attacks or LLM jailbreak attacks). + +- `systemPrompt`: You can override the default system prompt used by QvikChat by providing your own system prompt written using [Dotprompt]. If not provided, the default system prompt for the agent type will be used. +- `chatPrompt`: Chat prompt to use for the chat agent. If not provided, the default chat prompt for the agent type will be used. + +### Tools + +You can add tools to the execution flow of the chat endpoint. From adding simple task executing tools to complex action-taking agent workflows, you can configure the chat endpoint to use the tools you need. -- `agentType`: Type of chat agent to use for this endpoint. Can set it to "close-ended" to create a close-ended chat endpoint. By default, it is set to "open-ended". -- `topic`: Topic for close-ended chat agent. Required if RAG is enabled. Queries are restricted to be relevant to the given topic so to prevent unintended use. +- `tools`: Array of tools to use for the chat agent. + +### Context-Restricted Chat + +You can create a context-restricted chat endpoint by setting the `agentType` property to `close-ended`. This will create a close-ended chat endpoint that restricts queries to a specific topic. You must provide a `topic` for the close-ended chat agent. This is useful when you want to restrict the chat agent to a specific domain or topic. This helps prevent unintended use of the chat service by ignoring context irrelevant queries, for example, a chat service meant to answer user queries related to a product won't respond to queries about the weather. -**Chat History Configurations** +- `agentType`: Type of chat agent to use for this endpoint. Can set it to `close-ended` to create a close-ended chat endpoint. By default, it is set to `open-ended`. +- `topic`: Topic for close-ended chat agent. Required if either `agentType` is set to `close-ended` or if RAG is enabled. Queries are restricted to be relevant to the given topic so to prevent unintended use. + +### Chat History Configurations + +For adding the ability for the conversations to be continued, you can add support for chat history to the chat endpoint. To learn more about chat history, check [Chat History](/chat-history). - `enableChatHistory`: Enable chat history for this endpoint. If chat ID is provided, chat history will be fetched and used to generate response. If no chat ID is provided, a new chat ID will be generated to store chat history, and will be returned in the response. -- `chatHistoryStore`: Chat History Store instance to use for this endpoint. +- `chatHistoryStore`: [Chat History Store](/chat-history#chat-history-store) instance to use for this endpoint. + +### Auth Configurations -**Auth Configurations** +For adding authentication to the chat endpoint, you can enable authentication and provide an API Key Store instance. To learn more about authentication, check [Authentication](/authentication). - `enableAuth`: Enable authentication for this endpoint. Must provide an API Key Store instance if set to true. -- `apiKeyStore`: API Key Store instance to use for this endpoint. +- `apiKeyStore`: [API Key Store](/authentication#api-key-store) instance to use for this endpoint. -**Cache Configurations** +### Cache Configurations + +To cache responses to frequent queries and reduce response times and costs, you can enable caching for the chat endpoint. To learn more about caching, check [Caching](/caching). - `enableCache`: Enable caching for this endpoint. Must provide a Cache Store instance if set to true. -- `cacheStore`: Cache Store instance to use for this endpoint. +- `cacheStore`: [Cache Store](/caching#cache-store) instance to use for this endpoint. + +### RAG Configurations -**RAG Configurations** +Retrieval Augmented Generation (RAG) is a powerful technique that combines information retrieval with language generation to provide context-aware responses. You can enable RAG for the chat endpoint and provide a retriever method to retrieve documents for RAG. To learn more about RAG, check the [RAG Guide](/rag-guide). -- `topic`: Topic for RAG chat agent. Required if RAG is enabled. Queries are restricted to be relevant to the given topic so to prevent unintended use. -- `enableRAG`: Enable RAG (Retrieval Augmented Generation) functionality for this endpoint. Must provide a retriever method if set to true. -- `retriever`: Method to retrieve documents for RAG. Can be obtained from the `getDataRetriever` method. -- `retrieverConfig`: Configuration for the RAG retriever, for example, number of documents to retrieve, algorithm to use, etc. + -## Verbose Mode +### Observability & Usage You can set the `verbose` property to `true` to get additional information in the response. This may include usage information (like the number of input and output tokens used, input and output characters, etc.), tools calls information, and request details. +- `verbose`: If set to `true`, returns additional information in the response. May include usage information (like the number of input and output tokens used, input and output characters, etc.), tools calls information, and request details. By default, it is set to `false`. [Read more](#verbose-mode). + ```typescript copy defineChatEndpoint({ endpoint: "chat", @@ -120,12 +146,6 @@ Under the hood, each chat endpoint uses a `ChatAgent` to process the query and g You can use the `chatAgentConfig` property to override the default configurations for the chat agent. Below are the properties you can set in the `chatAgentConfig` object: -- `model`: Name of the LLM model to use for the chat agent. If not provided, the default model for the agent type will be used. -- `modelConfig`: Configuration for the LLM model. This can include parameters like temperature, max output tokens, and safety settings. -- `systemPrompt`: Default system prompt to use for the chat agent. If not provided, the default system prompt for the agent type will be used. -- `chatPrompt`: Default chat prompt to use for the chat agent. If not provided, the default chat prompt for the agent type will be used. -- `tools`: Array of tools to use for the chat agent. - Please ensure that you have configured the project to use the model, if you specify any specific model name. For using models through the Gemini API or OpenAI API, ensure that you've setup the [correct environment variables](/getting-started#environment-variables). For any other models, please ensure you've added the Genkit plugin correctly. For more information on setting up Genkit plugins, check [Genkit integration](/integrations/genkit). ## Example diff --git a/pages/core.mdx b/pages/core.mdx index 99bfd14..dc1f2d6 100644 --- a/pages/core.mdx +++ b/pages/core.mdx @@ -7,7 +7,7 @@ The typical workflow would look something like this: 1. **Define Endpoint Configurations:** Each chat service listens for incoming queries at a specific server endpoint. First step is to write the configurations for this chat endpoint. Through these configurations you can easily enable or disable features like chat history, cache, authentication, and RAG. You can also define the LLM model to be used for processing queries, besides other configurations. 2. **Configure and Run Server:** Once you have defined the chat endpoint configurations, you can use the `configureAndRunServer` method to start the server, passing a list of all endpoint configurations as an argument. Optionally, you can also provide configurations for the server (e.g. port number, cors, etc.), and the configurations for the Firebase Genkit (e.g. plugins you want to enable). -## Define Endpoint Configurations +## Chat Endpoint Configurations To configure a chat endpoint, we need to provide an object with the configurations for the endpoint. These configurations include the endpoint name, the configurations for chat history, cache, RAG, and more. You can use the `ChatEndpointConfig` type provided by QvikChat to define these configurations. @@ -54,7 +54,7 @@ configureAndRunServer({ port: 3444 ... // Other configurations for the server }, - genkitConfig: genkitConfig: { + genkitConfig: { plugins: [ ... // setup genkit plugins ], @@ -70,3 +70,33 @@ It performs the following three steps in sequential order: 1. **Setup Genkit:** Setup Firebase Genkit, either by using the default configurations or by using the configurations provided through the `genkitConfig` parameter. You can use this parameter to enable additional Genkit plugins or to add a different LLM model. 2. **Define Chat Endpoints:** Define the chat endpoints using the configurations provided in the `endpointConfigs` parameter. 3. **Run the Server:** Once Firebase Genkit is setup and the chat endpoints are defined, start an Express.js server to serve the endpoints. Use the default configurations for the server (e.g., for port number, cors, and other options) unless specific configurations provided for the server through the `serverConfig` parameter. + +## Define Chat Endpoint + +The `defineChatEndpoint` method can used to define chat endpoints manually before starting the server. Simply provide the configurations for the chat endpoint you want defined to this method directly. An example of how you can define a chat endpoint using the `defineChatEndpoint` method is shown below: + +```typescript +// Close-ended chat endpoint that allows users to ask only health and wellness related questions +defineChatEndpoint({ + endpoint: "health-chat", + topic: "Health and wellness", +}); +``` + +This is the method that gets called under the hood when you provide the list of endpoint configurations to the `configureAndRunServer` method. When using the `defineChatEndpoint` method, you will have to manually ensure that you setup Firebase Genkit, and that all endpoints are defined before you start the server. + +```typescript filename="index.ts" +import { defineChatEndpoint, runServer, setupGenkit } from "@oconva/qvikchat"; + +// Setup Genkit +setupGenkit(); + +// Chat endpoint that allows users to ask only health and wellness related questions +defineChatEndpoint({ + endpoint: "t", + topic: "health and wellness", +}); + +// Run server +runServer(); +``` diff --git a/pages/getting-started.mdx b/pages/getting-started.mdx index 8ff4ab7..d664093 100644 --- a/pages/getting-started.mdx +++ b/pages/getting-started.mdx @@ -6,6 +6,19 @@ QvikChat is a framework built on top of Firebase Genkit and LangChain. It allows If you wish to get started quickly with minimal setup or if you are planning to build a standalone server to serve chat endpoints, its recommended that you start with the [QvikChat Starter Template](#qvikchat-starter-template). It comes pre-configured with support for TypeScript, ESLint, Prettier, Jest, SWC, and more. +## How it works? + +Each chat service is defined by defining a **chat endpoint**. The chat endpoint that you define, is the code that gets called when a new request is received at that endpoint. You can define multiple chat services, each with its own endpoint. Each chat endpoint can have various attributes like input data schema, LLM model to be used for processing queries, authentication policy, etc. You defines these attributes when creating the configurations for the chat endpoint. + +This is the real superpower of QvikChat. You can define a chat endpoint with support for chat history, authentication, response caching, RAG, and more, in just a few lines of code. You can even store these configurations remotely and load them dynamically at runtime. + +There are two ways this can be done: + +1. **Using the `configureAndRunServer` method:** This is the easiest way to get started with QvikChat. You can provide a list of endpoint configurations to the `configureAndRunServer` method, and it will start the server with all the defined chat endpoints. To learn more about the `configureAndRunServer` method and the different configurations that you can provide, check the [Configure and Run Server](/core#configure-and-run-server) section. +2. **Using the `defineChatEndpoint` method:** You can directly call the `defineChatEndpoint` method with the configurations for the chat endpoint, anywhere in your codebase. This is the method that gets called under the hood when you provide the list of endpoint configurations to the `configureAndRunServer` method. When using the `defineChatEndpoint` method, you will have to manually ensure that you setup Firebase Genkit, and that all endpoints are defined before you start the server. To learn more about `defineChatEndpoint` method check the [Define Chat Endpoint](/core#define-chat-endpoint) section. + +In this guide, we are going to use the `configureAndRunServer` method to define chat endpoints and start the server. + ## Installing QvikChat Package You can install QvikChat using the following command: @@ -43,8 +56,8 @@ Alternatively, you can copy the `.env.tmp` file or rename it to `.env` and fill To use QvikChat, the typical workflow would look something like this: -1. **Define Endpoint Configurations:** Each chat service listens for incoming queries at a specific server endpoint. First step is to write the configurations for this chat endpoint. Through these configurations you can easily enable or disable features like chat history, cache, authentication, and RAG. You can also define the LLM model to be used for processing queries, besides other configurations. -2. **Configure and Run Server:** Once you have defined the chat endpoint configurations, you can use the `configureAndRunServer` method to start the server, passing a list of all endpoint configurations as an argument. Optionally, you can also provide configurations for the server (e.g. port number, cors, etc.), and the configurations for the Firebase Genkit (e.g. plugins you want to enable). +1. **Define Endpoint Configurations:** Each chat service listens for incoming queries at a specific server endpoint. First step is to write the configurations for this chat endpoint. Through these configurations you can easily enable or disable features like chat history, cache, authentication, and RAG. You can also define the LLM model to be used for processing queries, besides other configurations. To learn more about the different configurations that you can provide, check the [Chat Endpoint Configurations](/core#chat-endpoint-configurations) section. +2. **Configure and Run Server:** Once you have defined the chat endpoint configurations, you can use the `configureAndRunServer` method to start the server, passing a list of all endpoint configurations as an argument. Optionally, you can also provide configurations for the server (e.g. port number, cors, etc.), and the configurations for the Firebase Genkit (e.g. plugins you want to enable). To learn more about the `configureAndRunServer` method and the different configurations that you can provide, check the [Configure and Run Server](/core#configure-and-run-server) section. The below code shows a simple example of defining an open-ended chat endpoint in QvikChat. An open-ended chat endpoint basically allows queries related to any topic, i.e., it doesn't place any restrictions on what context the queries should be related to. @@ -74,7 +87,7 @@ Above example points to `http://127.0.0.1:3400`. You can change this port and ho ## QvikChat Starter Template -To get up and running quickly, you can use the QvikChat starter template. The starter template is a pre-configured project with all the necessary configurations and setup to get you started with QvikChat write quality and reliable code. It comes pre-configured with support for TypeScript, ESLint, Prettier, Jest, SWC, and more, so you can get started with developing the next revolutionary chat app right away, without worrying about all these things. +To get up and running quickly, you can use the **QvikChat starter template**. The starter template is a pre-configured project with all the necessary configurations and setup to get you started with QvikChat quickly while ensuring code quality and reliability. It comes pre-configured with support for TypeScript, ESLint, Prettier, Jest, SWC, and more, so you can get started with developing the next revolutionary chat service right away. ### Setup @@ -118,10 +131,10 @@ You can run the following commands to install the dependencies: npm install # or pnpm install ``` -To start the server, run: +To compile the project code and start the server, run: ```bash -npm run start # or pnpm start +npm run dev # or pnpm dev ``` Check the [testing endpoints](#testing-endpoints) section to learn how to test endpoints. @@ -191,11 +204,3 @@ Depending on which endpoint you wish to test, and where and on which port your s ```bash copy curl -X POST "http://127.0.0.1:3400/chat" -H "Content-Type: application/json" -d '{"data": { "query": "Answer in one sentence: What is Firebase Firestore?" } }' ``` - -## How it works? - -Each chat service is defined by defining a chat endpoint. The chat endpoint that you define, is the code that gets called when a new request is received at that endpoint. You can define multiple chat services, each with its own endpoint. Each chat endpoint can have various attributes like input data schema, LLM model to be used for processing queries, authentication policy, etc., and you can define these properties and the code that gets executed within an endpoint when defining a chat endpoint. - -QvikChat provides you with an extremely easy, flexible, and dynamic way to create server chat endpoints by simply using configurations. This is the real superpower of QvikChat. You can define a chat endpoint with support for chat history, authentication and response caching in just a few lines of code. You can even store these configurations remotely and load them dynamically at runtime. - -You can also use the `defineChatEndpoint` method to manually define a chat endpoint. Under the hood, this is the method that gets called when you provide the list of endpoint configurations to the `configureAndRunServer` method. To learn more about `defineChatEndpoint` method and the different chat endpoints that you can define, check the [Chat Endpoints](/chat-endpoints) section.