@or-sdk/qna - npm Package Compare versions

Comparing version 3.2.0-beta.1544.0 to 3.2.0-beta.1563.0

CHANGELOG.md

@@ -6,2 +6,20 @@ # Change Log
 
+## [3.1.3](https://gitlab.internal.onereach.io/onereach/platform/or-sdk-next/compare/@or-sdk/qna@3.1.2...@or-sdk/qna@3.1.3) (2023-07-06)
+
+
+### Bug Fixes
+
+* **qna:** make instructions nullable; update docs ([c8644f0](https://gitlab.internal.onereach.io/onereach/platform/or-sdk-next/commit/c8644f05233b9c1ad2e66e4d895b0d492dbef6bf))
+
+
+
+## [3.1.2](https://gitlab.internal.onereach.io/onereach/platform/or-sdk-next/compare/@or-sdk/qna@3.1.1...@or-sdk/qna@3.1.2) (2023-07-03)
+
+
+### Bug Fixes
+
+* **qna:** add error parser ([89db24a](https://gitlab.internal.onereach.io/onereach/platform/or-sdk-next/commit/89db24a08e3c202e784619d58521df465f392354))
+
+
+
 ## [3.1.1](https://gitlab.internal.onereach.io/onereach/platform/or-sdk-next/compare/@or-sdk/qna@3.1.0...@or-sdk/qna@3.1.1) (2023-07-03)
@@ -8,0 +26,0 @@

dist/types/QnA.d.ts

 import { Base, List } from '@or-sdk/base';
-import { LoadDocument, CreateCollection, Search, Ask, UpdateCollection, UpdateDocument, QnAConfig, Document, Collection, SearchResult, AskResults, Find, Property, CreatePassage, Passage, UpdatePassage, DeletedPassage } from './types';
+import { LoadDocument, CreateCollection, Search, Ask, UpdateCollection, UpdateDocument, QnAConfig, Document, Collection, SearchResult, AskResults, Find, Property, CreatePassage, Passage, UpdatePassage, DeletedPassage, FindPassages } from './types';
 export declare class QnA extends Base {
@@ -23,3 +23,3 @@ constructor(params: QnAConfig);
     listCollections(params?: Find): Promise<List<Collection>>;
-    listPassages<T extends Record<string, unknown>>(collectionId: string, params?: Find): Promise<List<Passage<T>>>;
+    listPassages<T extends Record<string, unknown>>(collectionId: string, params?: FindPassages): Promise<List<Passage<T>>>;
     listPassagesInDocument<T extends Record<string, unknown>>(collectionId: string, documentId: string, find?: Find): Promise<List<Passage<T>>>;
@@ -26,0 +26,0 @@ deleteDocument(collectionId: string, documentId: string): Promise<Document>;

dist/types/types.d.ts

@@ -43,4 +43,4 @@ import { OrderOptions, PaginationOptions, Token } from '@or-sdk/base';
     mode?: AskMode;
-    answerInstruction?: string;
-    questionInstruction?: string;
+    answerInstruction?: string | null;
+    questionInstruction?: string | null;
     temperature?: number;
@@ -73,5 +73,5 @@ maxTokens?: number;
     imageUrl?: string;
-    answerInstruction?: string;
-    questionInstruction?: string;
-    greetingInstruction?: string;
+    answerInstruction?: string | null;
+    questionInstruction?: string | null;
+    greetingInstruction?: string | null;
     properties?: Property[];
@@ -101,2 +101,8 @@ createdAt: string | Date;
     greetingInstruction?: string;
+    temperature?: number;
+    maxTokens?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    maxDistance?: number;
+    modelName?: string;
 };
@@ -107,3 +113,6 @@ export type Find = Partial<PaginationOptions> & Partial<OrderOptions> & {
 };
-export type CreatePassage<T extends Record<string, unknown>> = {
+export type FindPassages = Find & {
+    where?: Record<string, unknown>;
+};
+export type CreatePassage<T extends Record<string, unknown> = Record<string, unknown>> = {
     content: string;
@@ -113,3 +122,3 @@ documentId: string;
 } & T;
-export type Passage<T extends Record<string, unknown>> = {
+export type Passage<T extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
@@ -120,3 +129,3 @@ content: string;
 } & T;
-export type UpdatePassage<T extends Record<string, unknown>> = {
+export type UpdatePassage<T extends Record<string, unknown> = Record<string, unknown>> = {
     content: string;
@@ -123,0 +132,0 @@ } & T;

package.json

 {
   "name": "@or-sdk/qna",
-  "version": "3.2.0-beta.1544.0",
+  "version": "3.2.0-beta.1563.0",
   "main": "dist/cjs/index.js",
@@ -5,0 +5,0 @@ "module": "dist/esm/index.js",

README.md

@@ -174,27 +174,47 @@ # QnA SDK
 
-Create a new collection with optional properties. A collection is a group of related documents that are searchable together. You can define additional properties to store custom metadata associated with the passages within the collection.
+Creates a new collection with optional properties. A collection is a group of related documents that are searchable together. Additional custom properties can be defined to store metadata associated with the documents within the collection.
 
 #### Params
--  name: `string` - The name of the collection
--  description: `string` (optional) - A brief description of the collection
--  properties: `Property[]` (optional) - An array of custom properties to add to the collection. Each property should include a name, datatype, and an optional description. For more information on supported datatypes, visit https://weaviate.io/developers/weaviate/config-refs/schema#datatypes
 
+- `createParams`: `CreateCollection` - An object containing the properties of the collection:
+  - `name`: `string` - The name of the collection. It can start only with a letter and it must be at least 3 characters long, and cannot exceed 100 characters in length.
+  - `description`: `string` (optional) - A brief description of the collection. If present, it must be at least 3 characters and no more than 500 characters in length.
+  - `properties`: `Property[]` (optional) - An array of custom properties to add to the collection. Each property should include a name and datatype. Please see list of supported datatypes.
+  - `imageUrl`: `string` (optional) - The URL of the thumbnail image for the collection. It must be at least 3 characters and it cannot exceed 2048 characters in length.
+  - `answerInstruction`: `string` (optional) - An instruction used to generate a correct answer. If present, it cannot be more than 1000 characters long.
+  - `questionInstruction`: `string` (optional) - An instruction used to generate a proper search query. If present, it cannot be more than 1000 characters long.
+  - `greetingInstruction`: `string` (optional) - An instruction used to generate a correct first message. If present, it cannot be more than 1000 characters long.
+  - `temperature`: `number` (optional) - Sampling temperature to use. If present, it must be a number between 0 and 2.
+  - `maxTokens`: `number` (optional) - The maximum output length from the Large Language Model (LLM). If present, it must be a number between 128 and 2048.
+  - `frequencyPenalty`: `number` (optional) - Value to penalize new tokens based on their frequency in existing text. If present, it must be a number between -2 and 2.
+  - `presencePenalty`: `number` (optional) - Value to penalize new tokens based on their presence in existing text. If present, it must be a number between -2 and 2.
+  - `maxDistance`: `number` (optional) - Value to filter out passages that are further than this value from the question or context. If present, it must be a number between 0 and 1.
+  - `modelName`: `string` (optional) - Name of the large language model to be used. It can't be more than 64 characters long.
+
 #### Example
-Creating a collection with a name and description
+Creating a collection with a name, description, and additional instructions
 
 ```typescript
 const collection = await qna.createCollection({
-  description: 'A sample collection',
   name: 'Sample Collection',
+  description: 'A sample collection for QnA',
+  properties: [
+    { name: 'author', dataType: 'string' },
+    { name: 'year', dataType: 'int' },
+  ],
+  imageUrl: 'https://example.com/sample-collection.jpg',
+  answerInstruction: 'Provide relevant answer from the text',
+  questionInstruction: 'Generate a question based on understanding of the text',
+  greetingInstruction: 'Initiate conversation providing context about the document',
+  temperature: 0.7,
+  maxTokens: 200,
+  frequencyPenalty: 0.8,
+  presencePenalty: 1,
+  maxDistance: 0.5,
+  modelName: 'text-davinci-002'
 });
 
-// Example response
-{
-  id: 'a1b2c3d4-uuid',
-  accountId: 'i9j0k1l2-uuid',
-  name: 'Sample Collection',
-  description: 'A sample collection'
-}
+console.log(collection);
 ```
-
+This will print collection information with its ID, name, and other parameters. It will also include any custom properties.
 Creating a collection with additional properties
@@ -204,4 +224,4 @@
 const collectionWithProperties = await qna.createCollection({
+  name: 'Collection With Properties',
   description: 'A collection with properties',
-  name: 'Collection With Properties',
   properties: [
@@ -223,2 +243,25 @@ {
 {
+  id: 'a1b2c3d4-uuid',
+  accountId: 'i9j0k1l2-uuid',
+  name: 'Collection With Properties',
+  description: 'A collection with properties'
+  properties: [
+    {
+      id: 'e5f6g7h8-uuid',
+      name: 'author',
+      dataType: 'string',
+      description: 'Author of the document',
+    },
+    {
+      id: 'i9j0k1l2-uuid',
+      name: 'publishDate',
+      dataType: 'date',
+      description: 'Date when the document was published',
+    },
+  ],
+}
+```
+
+// Example response
+{
   id: 'x1y2z3w4-uuid',
@@ -381,3 +424,6 @@ accountId: 'i9j0k1l2-uuid',
 -  where: `Record<string, unknown>` (optional) - Weaviate filter object for advanced filtering. For more details, visit https://weaviate.io/developers/weaviate/api/graphql/filters
+-  select: `string[]` (optional) - Array of the custom properties to select
 -  mode: `AskMode` (optional) - Question mode, can be either 'ask' or 'conversation'. Default is 'conversation'
+-  answerInstruction: `string | null` (optional) - A summarization instruction used to generate correct answer. Maximum Length: 1000 characters
+-  questionInstruction: `string | null` (optional) - A summarization instruction used to generate correct search query. Maximum Length: 1000 characters
 -  temperature: `number` (optional) - Adjusts the randomness in the model's output. Default is 1. Accepts values between 0 and 2
@@ -416,7 +462,10 @@ -  maxTokens: `number` (optional) - Maximum output length from the language model. Default is 1024. Accepts values between 128 and 2048
   },
+  select: ['title', 'author', 'publishDate'],
   mode: 'conversation',
+  answerInstruction: 'Generate a brief and concise answer.',
+  questionInstruction: 'Find documents related to the meaning of life.',
   temperature: 0.8,
   maxTokens: 1500,
-  frequencyPenalty: 0.5,
-  presencePenalty: 0.5,
+  frequencyPenalty: 0.5;
+  presencePenalty: 0.5;
   maxDistance: 0.9,
@@ -476,11 +525,21 @@ });
 
-Update an existing collection's description. The collection must be previously created using the `createCollection` method. The updated collection will preserve its existing properties, ID, name, and associated documents.
+Update an existing collection's properties. The collection must be previously created using the `createCollection` method. The updated collection will preserve its existing properties, ID, and name, but its associated documents might be affected based on the new instructions.
 
 #### Params
--  collectionId: `string` - The ID of the collection you want to update
--  updateParams: `UpdateCollection` - An object containing the properties you want to update, which can include:
-  -  description: `string` (optional) - The new description for the collection
+- `collectionId`: `string` - The ID of the collection you want to update
+- `updateParams`: `UpdateCollection` - An object containing the properties you want to update:
+  - `description`: `string` (optional) - The new description for the collection. `Minimum length: 3, Maximum length: 500`
+  - `imageUrl`: `string` (optional) - A collection thumbnail image URL. `Minimum length: 3, Maximum length: 2048`
+  - `answerInstruction`: `string` (optional) - A summarization instruction used to generate a correct answer. `Maximum length: 1000`
+  - `questionInstruction`: `string` (optional) - A summarization instruction used to generate a correct search query. `Maximum length: 1000`
+  - `greetingInstruction`: `string` (optional) - A summarization instruction used to generate a correct first message. `Maximum length: 1000`
+  - `temperature`: `number` (optional) - What sampling temperature to use. Default value: 1 Range: [0, 2]
+  - `maxTokens`: `number` (optional) - Max output length from the Large Language Model (LLM). Range: [128, 2048]
+  - `frequencyPenalty`: `number` (optional) - Positive values penalize new tokens based on their existing frequency in the text. Range: [-2, 2]
+  - `presencePenalty`: `number` (optional) - Penalize new tokens based on whether they appear in the text. Range: [-2, 2]
+  - `maxDistance`: `number` (optional) - Filter out passages that are further then maxDistance from the question or context. Range: [0, 1]
+  - `modelName`: `string` (optional) - Name of the large language model to be used. `Maximum length: 64`
 
 #### Example
-Updating a collection's description
+Updating a collection's description and adding a new question instruction.
 
@@ -491,2 +550,6 @@ ```typescript
   description: 'Updated collection description',
+  questionInstruction: 'Consider the main theme of the document for the query',
+  maxTokens: 200,
+  temperature: 1.5,
+  modelName: 'gpt-3'
 });
@@ -499,3 +562,7 @@
   name: 'Sample Collection',
-  description: 'Updated collection description'
+  description: 'Updated collection description',
+  questionInstruction: 'Consider the main theme of the document for the query',
+  maxTokens: 200,
+  temperature: 1.5,
+  modelName: 'gpt-3'
 }
@@ -746,23 +813,23 @@ ```
 
-List all passages in a collection with optional pagination, search query filtering, and search type. This method allows you to retrieve passages from a collection and optionally filter them based on a search query, page size, and offset.
+List all passages in a collection with optional pagination, search query filtering, and search mode. This method allows you to retrieve passages from a collection and optionally filter them based on a search query, page size, and offset.
 
 #### Params
--  collectionId: `string` - The ID of the collection to retrieve passages from
--  params: `ListPassages` (optional) - An object containing the following optional properties:
-  - `query` (string, optional): Search query for filtering passages
-  - `from` (number, optional): Pagination offset (index of the first item in the current page)
-  - `size` (number, optional): Maximum number of passages to retrieve (page size)
-  - `alpha` (number, optional): Weight between sparse and vector search. A value of `0` represents a pure sparse search, while a value of `1` represents a pure vector search. Values between `0` and `1` control the balance between the two search modes.
+- `collectionId`: `string` - The ID of the collection to retrieve passages from.
+- `params`: `FindPassages` (optional) - An object containing the following optional properties:
+  * `query`: `string` (optional): Search query for filtering passages.
+  * `from`: `number` (optional): Pagination offset (the index of the first item on the page).
+  * `size`: `number` (optional): Maximum number of passages to retrieve (page size).
+  * `mode`: `SearchMode` (optional) - The search mode, either 'bm25' for full-text search or 'vector' for vector similarity search. Default is 'bm25'
+  * `where`: `Record<string, unknown>` (optional): A weaviate where filter. See [Weaviate Filters](https://www.semi.technology/developers/weaviate/current/graphql-references/filters.html) for more information.
 
 #### Example
+Listing passages with pagination, query filter, and a specific search mode:
 
-Listing passages with pagination and query filter:
-
 ```typescript
 const collectionId = 'a1b2c3d4-uuid';
-const params: ListPassages = {
+const params: FindPassages = {
   query: 'sample query',
   from: 0,
   size: 10,
-  alpha: 0.5,
+  mode: 'vector',
 };
@@ -777,3 +844,3 @@ const passages = await qna.listPassages(collectionId, params);
       content: 'This is the content of the passage.',
-      // ...more properties
+      // ...other properties
     },
@@ -785,2 +852,3 @@ // ...more passages
 ```
+This will return a list of passages from the specified collection that match the filter query and are ordered according to their vector similarity. It also supports a 'where' query for advanced filtering.
 
@@ -787,0 +855,0 @@ ### `listPassagesInDocument`

src/QnA.ts

@@ -13,2 +13,3 @@ import { Base, List, makeList } from '@or-sdk/base';
   DeletedPassage,
+  FindPassages,
 } from './types';
@@ -313,3 +314,3 @@ import { createErrorParser, processors } from './error-parser';
     collectionId: string,
-    params: Find = {},
+    params: FindPassages = {},
   ): Promise<List<Passage<T>>> {
@@ -316,0 +317,0 @@ const response = await this.callApiV2<Passage<T>[]>({

src/types.ts

@@ -177,3 +177,3 @@ import { OrderOptions, PaginationOptions, Token } from '@or-sdk/base';
    */
-  answerInstruction?: string;
+  answerInstruction?: string | null;
 
@@ -185,3 +185,3 @@ /**
    */
-  questionInstruction?: string;
+  questionInstruction?: string | null;
 
@@ -309,17 +309,17 @@ /**
    * A summarization instruction used to generate a correct answer (Optional)
-   * Maximum length: 1000
+   * Maximum length: 2048
    */
-  answerInstruction?: string;
+  answerInstruction?: string | null;
 
   /**
    * A summarization instruction used to generate a correct search query (Optional)
-   * Maximum length: 1000
+   * Maximum length: 2048
    */
-  questionInstruction?: string;
+  questionInstruction?: string | null;
 
   /**
    * A summarization instruction used to generate a correct first message (Optional)
-   * Maximum length: 1000
+   * Maximum length: 2048
    */
-  greetingInstruction?: string;
+  greetingInstruction?: string | null;
 
@@ -432,2 +432,39 @@ /**
   greetingInstruction?: string;
+
+  /**
+   * What sampling temperature to use (Optional)
+   * Default value: 1, Range: [0, 2]
+   */
+  temperature?: number;
+
+  /**
+   * Max output length from the LLM (Optional)
+   * Range: [128, 2048]
+   */
+  maxTokens?: number;
+
+  /**
+   * Positive values penalize new tokens based on their existing frequency in the text so far (Optional)
+   * Range: [-2, 2]
+   */
+  frequencyPenalty?: number;
+
+  /**
+   * Penalize new tokens based on whether they appear in the text so far (Optional)
+   * Range: [-2, 2]
+   */
+  presencePenalty?: number;
+
+  /**
+   * Filter out passages that are further then maxDistance from the question or context by
+   * cosine metric (Optional)
+   * Range: [0, 1]
+   */
+  maxDistance?: number;
+
+  /**
+   * Large language model name (Optional)
+   * Maximum length: 64
+   */
+  modelName?: string;
 };
@@ -451,5 +488,15 @@
 /**
+ * Find passages parameters
+ */
+export type FindPassages = Find & {
+  /**
+   * Weaviate where filter. See https://weaviate.io/developers/weaviate/api/graphql/filters
+   */
+  where?: Record<string, unknown>;
+};
+
+/**
  * Passage creation parameters. The properties other than listed are considered custom properties.
  */
-export type CreatePassage<T extends Record<string, unknown>> = {
+export type CreatePassage<T extends Record<string, unknown> = Record<string, unknown>> = {
   /**
@@ -474,3 +521,3 @@ * Content of the passage
  */
-export type Passage<T extends Record<string, unknown>> = {
+export type Passage<T extends Record<string, unknown> = Record<string, unknown>> = {
   /**
@@ -501,3 +548,3 @@ * Passage ID
  */
-export type UpdatePassage<T extends Record<string, unknown>> = {
+export type UpdatePassage<T extends Record<string, unknown> = Record<string, unknown>> = {
   /**
@@ -504,0 +551,0 @@ * Updated content of the passage

No alert changes

Improved metrics

Total package byte prevSize

161720

increased by5.22%

Lines of code

2477

increased by2.06%

Number of lines in readme file

987

increased by7.4%

No dependency changes