re-organized chat endpoints pages + minor updates

oconva · Jul 14, 2024 · bf5c06e · bf5c06e
1 parent 2490e33
commit bf5c06e
Show file tree

Hide file tree

Showing 11 changed files with 298 additions and 294 deletions.
diff --git a/pages/_meta.json b/pages/_meta.json
@@ -11,8 +11,11 @@
   "caching": "Caching",
   "authentication": "Authentication",
   "integrations": "Integrations",
-  "another": {
-    "display": "hidden"
+  "deployment": "Deployment",
+  "Examples": {
+    "title": "Examples ↗",
+    "href": "https://github.com/oconva/qvikchat-examples",
+    "newWindow": true
   },
   "about": {
     "title": "About",

diff --git a/pages/chat-endpoints.mdx b/pages/chat-endpoints.mdx
@@ -1,3 +1,5 @@
+import Img from "../components/img";
+
 # Chat Endpoints
 
 You can define various chat endpoints based on your requirements.
@@ -33,3 +35,12 @@ Chat endpoint where user queries are restricted to a specific topic. Prevents mi
 Context-aware and topic-specific chat with ability to answer user queries by retrieving additional context information from a knowledge base (e.g. from a JSON file or PDF).
 
 [Read more](chat-endpoints/rag-chat)
+
+Below images gives a high-level overview of how a user query is handled in a RAG chat endpoint.
+
+<Img
+  src="/images/rag-history-endpoint-query.png"
+  showSubtitle="true"
+  subtitle="High-level overview of how chat endpoints handle user queries"
+  priority={false}
+/>
diff --git a/pages/chat-endpoints/_meta.json b/pages/chat-endpoints/_meta.json
@@ -1,5 +1,7 @@
 {
-  "open-ended-chat": "Open Ended Chat",
-  "close-ended-chat": "Close Ended Chat",
-  "rag-chat": "RAG Chat"
+  "open-ended-chat": "Open-ended Chat",
+  "close-ended-chat": "Close-ended Chat",
+  "rag-chat": "RAG Chat",
+  "chat-endpoint-configurations": "Chat Endpoint Configurations",
+  "testing-endpoints": "Testing Endpoints"
 }
diff --git a/pages/chat-endpoints/close-ended-chat.mdx b/pages/chat-endpoints/close-ended-chat.mdx
@@ -1,4 +1,4 @@
-# Close Ended Chat
+# Close-ended Chat
 
 Chat endpoint where user queries are restricted to a specific topic. Prevents misuse of the chat service by restricting the usage, for example, a chat service meant to answer queries related to a specific topic like Firebase won't answer user queries related to other topics like solving a calculus assignment question.
 
@@ -14,26 +14,41 @@ Below are some of the close-ended chat endpoints you can define.
 
 Restricted chat to a specific topic with no chat history support.
 
-### Expected Input Schema
+### Usage
+
+Below is an example of how you can define a close-ended chat endpoint. You can use the `topic` field to specify the topic for which this endpoint should answer queries.
+
+```typescript copy
+// Close-ended chat endpoint
+// will only answer queries related to specified topic, in this case, 'Firebase'
+defineChatEndpoint({
+  endpoint: "chat-close",
+  agentType: "close-ended",
+  topic: "Firebase",
+});
+```
+
+### Input Schema
+
+Expects an object with the following properties:
 
-- `data`: User query to chat agent.
+- `query`: User query to chat agent.
 
   ```json
   {
-    "data": "string",
-    "required": ["data"]
+    "query": "string"
   }
   ```
 
 ### Output Schema
 
 For successful requests, the response will contain:
 
-- `result`: Chat agent response to the user query, returned as a string by default. (You may add more endpoints or update existing ones under `src/endpoints`)
+- `response`: Chat agent response to the user query, returned as a string by default. (You may add more endpoints or update existing ones under `src/endpoints`)
 
   ```json
   {
-    "result": "string"
+    "response": "string"
   }
   ```
 
@@ -47,21 +62,9 @@ For failed requests, the response will contain:
   }
   ```
 
-### Usage
-
-Below is an example of how you can define a close-ended chat endpoint. You can use the `topic` field to specify the topic for which this endpoint should answer queries.
-
-```typescript copy
-// Close-ended chat endpoint
-// will only answer queries related to specified topic, in this case, 'Firebase'
-defineChatEndpoint({
-  endpoint: "chat-close",
-  agentType: "close-ended",
-  topic: "Firebase",
-});
-```
+### Testing
 
-Can use commands below to test this endpoint.
+Can use commands below to test the endpoint defined in the example above.
 
 For the first example, ideally, you should get a response that the model can't answer the question since it's not related to the specified topic, establishing that the chat agent is working as expected. It should, however, generate a proper answer for the second example.
 
@@ -71,7 +74,7 @@ curl -X POST "http://127.0.0.1:3400/chat-close" -H "Content-Type: application/js
 curl -X POST "http://127.0.0.1:3400/chat-close" -H "Content-Type: application/json"  -d '{"data": { "query" : "What is App check?" } }'
 ```
 
-#### Genkit Developer UI
+**Genkit Developer UI**
 
 You could also start the Genkit Developer UI to test above:
 
@@ -85,18 +88,32 @@ Endpoint to test: `chat-close`
 
 Restricted chat to a specific topic with chat history support.
 
-### Expected Input Schema
+### Usage
+
+Below is an example of how you can define a close-ended chat endpoint that supports chat history. Simply, set the `enableChatHistory` flag to `true` and provide an a chat history store. For testing, you may use the in-memory chat history store.
+
+```typescript copy   copy {8}
+// Close-ended chat endpoint with support for chat history
+defineChatEndpoint({
+  endpoint: "chat-close-history",
+  agentType: "close-ended",
+  topic: "Firebase",
+  enableChatHistory: true,
+  chatHistoryStore: new InMemoryChatHistoryStore(),
+});
+```
+
+### Input Schema
+
+Expects an object with the following properties:
 
 - `query`: User query to chat agent.
 - `chatId`: Optional chat ID to continue the chat history. If not provided, a new chat history will be created, and the chat ID for this chat history will be returned with the response. This chat ID can be sent in further requests to continue a specific conversation. If the provided chat ID is not valid or not found, as error is returned.
 
   ```json
   {
-    "data": {
-      "query": "string",
-      "chatId": "string"
-    },
-    "required": ["query"]
+    "query": "string",
+    "chatId": "string"
   }
   ```
 
@@ -109,10 +126,8 @@ For successful requests, the response will contain:
 
   ```json
   {
-    "result": {
-      "response": "string",
-      "chatId": "string"
-    }
+    "response": "string",
+    "chatId": "string"
   }
   ```
 
@@ -126,28 +141,17 @@ For failed requests, the response will contain:
   }
   ```
 
-### Usage
+### Testing
 
-Below is an example of how you can define a close-ended chat endpoint that supports chat history. Simply, set the `enableChatHistory` flag to `true` and provide an a chat history store. For testing, you may use the in-memory chat history store.
-
-```typescript copy   copy {8}
-// Close-ended chat endpoint with support for chat history
-defineChatEndpoint({
-  endpoint: "chat-close-history",
-  agentType: "close-ended",
-  topic: "Firebase",
-  enableChatHistory: true,
-  chatHistoryStore: new InMemoryChatHistoryStore(),
-});
-```
+Can use commands below to test the endpoint defined in the example above.
 
 ```bash copy
 curl -X POST "http://127.0.0.1:3400/chat-close-history" -H "Content-Type: application/json"  -d '{"data": { "query": "What is App check?" } }'
 
 curl -X POST "http://127.0.0.1:3400/chat-close-history" -H "Content-Type: application/json"  -d '{"data": { "query": "By using this, can you block traffic that does not have valid credentials?", "chatId": "<enter chat id here>" } }'
 ```
 
-### Genkit Developer UI
+**Genkit Developer UI**
 
 You could also start the Genkit Developer UI to test above:
 
@@ -161,26 +165,54 @@ Endpoint to test: `chat-close-history`
 
 Restricted chat to a specific topic with chat history support, response caching, and API key authentication.
 
-### Expected Input Schema
+### Usage
+
+Below example displays how you can define a close-ended chat endpoint that supports chat history, response caching, and API key authentication.
+
+The example below uses in-memory stores for chat history, caching and API key Storage, but you can easily provide your own stores when configuring the endpoint.
+
+```typescript copy
+// Initialize a Test API key store
+const testAPIKeyStore = new InMemoryAPIKeyStore();
+// add a test API key
+const key = "test-api-key";
+testAPIKeyStore.addKey(key, {
+  uid: "test-user",
+  status: "active",
+  endpoints: "all", // allow access to all endpoints
+});
+
+// Close-ended chat endpoint with support for chat history, authentication, and caching
+defineChatEndpoint({
+  agentType: "close-ended",
+  topic: "Firebase",
+  endpoint: "chat-close-history-auth-cached",
+  enableChatHistory: true,
+  chatHistoryStore: new InMemoryChatHistoryStore(),
+  enableAuth: true,
+  apiKeyStore: testAPIKeyStore,
+  enableCache: true,
+  cacheStore: new InMemoryCacheStore(),
+});
+```
+
+### Input Schema
 
 Request header requires an API key for authentication:
 
 - `key`: API key for authentication. The API key must be owned by the user making the request, and should have authorization to access the endpoint endpoint.
 
-Request body data:
+In request data, expects an object with the following properties:
 
 - `query`: User query to chat agent.
 - `uid`: User ID of the user making the query. Required to assess if user is authorized to access the endpoint endpoint. The API key provided in headers must be owned by this user.
 - `chatId`: Optional chat ID to continue the chat history. If not provided, a new chat history will be created, and the chat ID for this chat history will be returned with the response. This chat ID can be sent in further requests to continue a specific conversation. If the provided chat ID is not valid or not found, as error is returned.
 
   ```json
   {
-    "data": {
-      "query": "string",
-      "uid": "string",
-      "chatId": "string"
-    },
-    "required": ["query", "uid"]
+    "query": "string",
+    "uid": "string",
+    "chatId": "string"
   }
   ```
 
@@ -193,10 +225,8 @@ For successful requests, the response will contain:
 
   ```json
   {
-    "result": {
-      "response": "string",
-      "chatId": "string"
-    }
+    "response": "string",
+    "chatId": "string"
   }
   ```
 
@@ -210,36 +240,19 @@ For failed requests, the response will contain:
   }
   ```
 
-### Usage
-
-Below example displays how you can define a close-ended chat endpoint that supports chat history, response caching, and API key authentication. The example below uses in-memory stores for chat history, caching and API key Storage, but you can easily provide your own stores when configuring the endpoint.
-
-```typescript copy
-// Close-ended chat endpoint with support for chat history, authentication, and caching
-defineChatEndpoint({
-  agentType: "close-ended",
-  topic: "Firebase",
-  endpoint: "chat-close-history-auth-cached",
-  enableChatHistory: true,
-  chatHistoryStore: new InMemoryChatHistoryStore(),
-  enableAuth: true,
-  apiKeyStore: new InMemoryAPIKeyStore(),
-  enableCache: true,
-  cacheStore: new InMemoryCacheStore(),
-});
-```
+### Testing
 
-You can use the commands below to test this endpoint.
+Can use commands below to test the endpoint defined in the example above.
 
 On running the first example, you should receive an object as a response with the chat ID for the chat history. Add this chat ID to the second example to continue the chat history.
 
 ```bash copy
-curl -X POST "http://127.0.0.1:3400/chat-close-history-auth-cached" -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY" -d '{"data": { "query": "What is App check?" } }'
+curl -X POST "http://127.0.0.1:3400/chat-close-history-auth-cached" -H "Content-Type: application/json" -H "Authorization: test-api-key" -d '{"data": { "query": "What is App check?", "uid": "test-user" } }'
 
-curl -X POST "http://127.0.0.1:3400/chat-close-history-auth-cached" -H "Content-Type: application/json" -H "Authorization: YOUR_API_KEY" -d '{"data": { "query": "By using this, can you block traffic that does not have valid credentials?", "chatId": "<enter chat id here>" } }'
+curl -X POST "http://127.0.0.1:3400/chat-close-history-auth-cached" -H "Content-Type: application/json" -H "Authorization: test-api-key" -d '{"data": { "query": "By using this, can you block traffic that does not have valid credentials?", "uid": "test-user", "chatId": "<enter chat id here>" } }'
 ```
 
-### Genkit Developer UI
+**Genkit Developer UI**
 
 You could also start the Genkit Developer UI to test above: