@or-sdk/qna

QnA SDK

The @or-sdk/qna package provides a client for working with the QnA (Question and Answer) system in OneReach.ai. With this client, you can perform operations such as loading documents, creating collections, searching in collections, asking questions to generate answers based on the loaded documents, and managing properties of collections.

Concepts

Collection

A collection is a group of searchable items, also known as passages. It allows you to organize and manage related documents and their passages together under a single entity. When you perform a search or ask a question, the QnA system will search through the passages within the specified collection.

Document

Documents are used to load a bulk of data into a collection. They can be any type of text-based file such as PDFs, text files, or web pages. When you provide a URL for a document, the QnA system downloads the content, splits it into smaller chunks (passages), and adds them to the collection.

Passage

A passage is an atomic piece of data that represents a portion of a document. It is the smallest searchable unit within a collection. When you search or ask a question, the QnA system uses vector similarity to find the most relevant passages from all the documents in the collection.

The search process involves comparing the vector representation of the input query (search term or question) with the vector representations of the passages in the collection. The results are ranked based on the similarity between the query and passages, with the most similar passages being returned as the search results.

Property

A property is an additional piece of information that can be added to a collection to store custom metadata about the collection. Properties can have a name, datatype, and an optional description. You can manage properties by adding, updating, or deleting them from a collection.

Installation

To install the package, run the following command:

$ npm install @or-sdk/qna

Usage

To use the QnA client, you need to create an instance of the class with the appropriate configuration options. You can either provide the direct API URL or the service discovery URL. Here is an example:

import { QnA } from '@or-sdk/qna';

// with direct api url
const qna = new QnA({
  token: 'my-account-token-string',
  serviceUrl: 'http://example.qna/endpoint'
});

// with service discovery(slower)
const qna = new QnA({
  token: 'my-account-token-string',
  discoveryUrl: 'http://example.qna/endpoint'
});

Once you have an instance of the QnA client, you can use its methods to interact with the OneReach.ai QnA system. The available methods are:

Methods

loadDocument

Load a document into a collection.

const collectionId = 'a1b2c3d4-uuid';
const document = await qna.loadDocument(collectionId, {
  description: 'A sample document',
  url: 'http://example.com/sample-document.pdf',
  name: 'Sample Document',
});

// Example response
{
  id: 'e5f6g7h8-uuid',
  accountId: 'i9j0k1l2-uuid',
  collection: 'a1b2c3d4-uuid',
  name: 'Sample Document',
  description: 'A sample document'
}

createCollection

Create a new collection.

const collection = await qna.createCollection({
  description: 'A sample collection',
  name: 'Sample Collection',
});

// Example response
{
  id: 'a1b2c3d4-uuid',
  accountId: 'i9j0k1l2-uuid',
  name: 'Sample Collection',
  description: 'A sample collection'
}

Creating a collection with additional properties

const collectionWithProperties = await qna.createCollection({
  description: 'A collection with properties',
  name: 'Collection With Properties',
  properties: [
    {
      name: 'author',
      dataType: 'string',
      description: 'Author of the document',
    },
    {
      name: 'publishDate',
      dataType: 'date',
      description: 'Date when the document was published',
    },
  ],
});

// Example response
{
  id: 'x1y2z3w4-uuid',
  accountId: 'i9j0k1l2-uuid',
  name: 'Collection With Properties',
  description: 'A collection with properties',
  properties: [
    {
      name: 'author',
      dataType: 'string',
      description: 'Author of the document',
    },
    {
      name: 'publishDate',
      dataType: 'date',
      description: 'Date when the document was published',
    },
  ],
}

addProperty

Add a property to an existing collection. Note: We have reserved property names ['accountId', 'collection', 'document', 'content', 'loaderMetadata']. Data types details can be found at https://weaviate.io/developers/weaviate/config-refs/schema#datatypes

const collectionId = 'a1b2c3d4-uuid';
const property = {
  name: 'author',
  dataType: 'string',
  description: 'Author of the document',
};

await qna.addProperty(collectionId, property);

// No direct response, the property is added to the collection

You can verify the added property by retrieving the collection:

const collection = await qna.getCollection(collectionId);

// Example response
{
  id: 'a1b2c3d4-uuid',
  accountId: 'i9j0k1l2-uuid',
  name: 'Sample Collection',
  description: 'A sample collection',
  properties: [
    {
      name: 'author',
      dataType: 'string',
      description: 'Author of the document',
    },
  ],
}

deleteCollection

Delete a collection by its ID.

const collectionId = 'a1b2c3d4-uuid';
await qna.deleteCollection(collectionId);

search

Search for documents in a collection.

const collectionId = 'a1b2c3d4-uuid';
const searchResults = await qna.search(collectionId, {
  term: 'search term',
  limit: 10,
});

// Example response
[
  {
    id: 'e5f6g7h8-uuid',
    distance: '0.1234',
    content: 'Found passage content',
    metadata: {}
  }
]

// Using where and select options
const searchResultsWithOptions = await qna.search(collectionId, {
  term: 'search term',
  limit: 10,
  where:  {
    operator: 'Equal',
    path: [ 'author'],
    valueString: 'John Doe'
  },
  select: ['author', 'publishDate'],
});

// Example response
[
  {
    id: 'e5f6g7h8-uuid',
    distance: '0.1234',
    content: 'Found passage content',
    author: 'John Doe',
    publishDate: '2020-12-31'
  }
]

ask

Ask a question and generate an answer based on the documents in a collection.

const collectionId = 'a1b2c3d4-uuid';
const askResults = await qna.ask(collectionId, {
  question: 'What is the meaning of life?',
  messages: [
    { role: 'user', content: 'Hello' },
    { role: 'assistant', content: 'Hi there!' },
  ],
  limit: 10,
});

// Example response
{
  result: { role: 'assistant', content: 'The meaning of life is 42.' },
  searchResult: {
    id: 'e5f6g7h8-uuid',
    distance: '0.1234',
    content: 'Found passage content',
    metadata: {}
  }
}

updateDocument

Update a document's description.

const collectionId = 'a1b2c3d4-uuid';
const documentId = 'e5f6g7h8-uuid';
const updatedDocument = await qna.updateDocument(collectionId, documentId, {
  description: 'Updated document description',
});

// Example response
{
  id: 'e5f6g7h8-uuid',
  accountId: 'i9j0k1l2-uuid',
  collection: 'a1b2c3d4-uuid',
  name: 'Sample Document',
  description: 'Updated document description'
}

updateCollection

Update a collection's description.

const collectionId = 'a1b2c3d4-uuid';
const updatedCollection = await qna.updateCollection(collectionId, {
  description: 'Updated collection description',
});

// Example response
{
  id: 'a1b2c3d4-uuid',
  accountId: 'i9j0k1l2-uuid',
  name: 'Sample Collection',
  description: 'Updated collection description'
}

getDocument

Get a document by its ID.

const collectionId = 'a1b2c3d4-uuid';
const documentId = 'e5f6g7h8-uuid';
const document = await qna.getDocument(collectionId, documentId);

// Example response
{
  id: 'e5f6g7h8-uuid',
  accountId: 'i9j0k1l2-uuid',
  collection: 'a1b2c3d4-uuid',
  name: 'Sample Document',
  description: 'A sample document'
}

getCollection

Get a collection by its ID.

const collectionId = 'a1b2c3d4-uuid';
const collection = await qna.getCollection(collectionId);

// Example response
{
  id: 'a1b2c3d4-uuid',
  accountId: 'i9j0k1l2-uuid',
  name: 'Sample Collection',
  description: 'A sample collection'
}

listDocuments

List documents in a collection with optional pagination and query.

const collectionId = 'a1b2c3d4-uuid';
const documents = await qna.listDocuments(collectionId, {
  query: 'search query',
  size: 10,
  skip: 0,
});

// Example response
```json
{
  "items": [
    {
      "id": "e5f6g7h8-uuid",
    "accountId": "i9j0k1l2-uuid",
    "collection": "a1b2c3d4-uuid",
    "name": "Sample Document",
    "description": "A sample document"
    }
  ],
  "total": 1
}

listCollections

List collections with optional pagination and query.

const collections = await qna.listCollections({
  query: 'search query',
  size: 10,
  skip: 0,
});

// Example response
{
  "items": [
    {
      "id": "a1b2c3d4-uuid",
      "accountId": "i9j0k1l2-uuid",
      "name": "Sample Collection",
      "description": "A sample collection"
    }
  ],
  "total": 1
}

deleteDocument

Delete a document from a collection.

const collectionId = 'a1b2c3d4-uuid';
const documentId = 'e5f6g7h8-uuid';
await qna.deleteDocument(collectionId, documentId);