soco.ai

NodeJS client for SOCO.ai.

Usage no npm install needed!

<script type="module">
  import socoAi from 'https://cdn.skypack.dev/soco.ai';
</script>

README

SOCO.ai JavaScript/TypeScript Client

NodeJS client for SOCO.ai.

Build Status Coverage Status

Install

npm install soco.ai

Usage

import { SocoClient, Config } from 'soco.ai';

const config: Config = {
  adminApiKey: '...', // needed for Admin APIs
  clientId: '...', // needed for APIs & Parse Doc API
  queryApiKey: '...',// needed for Query APIs
};
const client = new SocoClient(config);

Query / Search

Using:

import { QueryRequest } from 'soco.ai';
const request: QueryRequest = {
  uid: 'ID of the end user',
  query: {
    query: 'who is Jimmy?',
    n_best: 3
  }
};
const answers = await client.query(request);

Waiting for Operation to Finish

It is possible to pass waitUntilOpFinished to SocoClient functions, that call APIs that return an operation ID, which will make the function wait until the operation is finished or failed. The default value of waitUntilOpFinished is false. If waitUntilOpFinished set to true,

const waitUntilOpFinished = true;
const response = await client.addDocs(request, waitUntilOpFinished);

The function that waits for operation to be finished is available as well.

const operationId = '...';
const status = client.waitUntilFinished(operationId);

Using:

Add Documents

Using:

import { AddDocsRequest } from 'soco.ai';

const request: AddDocsRequest = {
  data: [
    {
      data: [{ text: 'there was bear called Jimmy', type: 'content' }],
      meta: { doc_id: '123' },
      doc_type: 'soco_doc'
    }
  ],
  auto_index: true
};

const response = await client.addDocs(request, true);

Add FAQs from CSV files

Using:

const filePath = 'test/e2e/fixtures/dataset-1'; // dir with CSV files 
const response = await client.addFAQsFromCSVs(filePath, {}, true, true);

Add unstructured data (PDF or MS Word)

Using:

import { ParseDocRequest } from 'soco.ai';
const parseRequest: ParseDocRequest = {
  client_id: 'a client ID',
  file_type: 'url',
  file_url: 'http://qiiip.org/Adobe Acrobat Reader FAQs.pdf',
  lang: 'en',
};

const response = await client.addUnstructuredDoc(parseRequest, undefined, true, true);

Read documents

Using:

import { ReadDocsRequest } from 'soco.ai';
const request: ReadDocsRequest = {
  skip: 0,
  limit: 10
};
const response = await client.readDocs(request);

Update documents

Using:

import { UpdateDocsRequest } from 'soco.ai';
const request: UpdateDocsRequest = {
  data: [
    {
      _id: '...',
      data: [{ text: 'ok, lets talk about something else', type: 'content' }],
      meta: { someMeta: 'mata info is mandatory' },
      doc_type: 'soco_doc'
    }
  ]
};

const response = await client.updateDocs(request, true);

Delete documents

Using:

If data is left empty or undefined, it removes all the documents.

import { DeleteDocsRequest } from 'soco.ai';
export const request: DeleteDocsRequest = {
  doc_ids: undefined,
  auto_index: false,
};

const response = await client.deleteDocs(request, true);

Aggregate Documents

Using:

If data is left empty or undefined, it removes all the documents.

import { AggregateDocsRequest } from 'soco.ai';
const request: AggregateDocsRequest = { field: '$meta.doc_id' };
const response = await client.aggregateDocs(request);

Reindex

Using:

import { ReindexRequest } from 'soco.ai';
const request: ReindexRequest = {
  params: { lm: {}, qa: {}, kw: {}, qq: {}, tuple: {} },
};
const answers = await client.reindex(request);

Refresh

Using:

import { RefreshRequest } from 'soco.ai';
const request: RefreshRequest = {
  params: { lm: {}, qa: {}, kw: {}, qq: {}, tuple: {} }
};
const answers = await client.refresh(request);

Get Operation Status

Using:

const operationId = response.op_id;
const status = await client.getOperationStatus(operationId);

Get Operations

Using:

const operations = await client.readOperations(0, 10, -1);

Error Handling

When API fails to return the result, it SocoClient functions throw an error with all the details.

Examples

Load CSV and PDF data

CSV files with FAQ need to be in this structure. There can/should be multiple questions leading to a single answer to improve matching accuracy.

question         ,answer
how are you doing,I am doing fine
how is it going  ,I am doing fine
how is life      ,It is fine
how old are you  ,I am 42 years old
what is your age ,I am 42 years old

import { SocoClient, Config, ReindexRequest, ParseDocRequest } from "soco.ai";

const pdfFile = "http://path to your pdf.pdf"; // there is no OCR, plain text needs to be in the PDF 
const csvFolder = "/Users/path to your folder with CSV files";

async function loadData() {
  // create config with secrets 
  const config: Config = {
    adminApiKey: "copy paste the key here from https://app.soco.ai",
    clientId: "copy paste the key here from https://app.soco.ai",
    queryApiKey: "copy paste the key here from https://app.soco.ai"
  };
  // create SOCO client
  const client = new SocoClient(config);
 
  // delete all the docs from SOCO (if needed, to ensure clean start)
  await client.deleteDocs({ doc_ids: undefined, auto_index: true }, true);
  
  // refresh all indexes
  const request: ReindexRequest = {
    params: { lm: {}, qa: {}, kw: {}, qq: {}, tuple: {} }
  };
  await client.reindex(request, true);
  
  // add FAQs from CSV files
  await client.addFAQsFromCSVs(csvFolder, {}, true, true);
 
  // add content of PDF file (unstructured data)
  const parseRequest: ParseDocRequest = {
    client_id: config.clientId,
    file_type: "url",
    file_url: pdfFile,
    lang: "en"
  };
  await client.addUnstructuredDoc(parseRequest, {}, true, true);

  // refresh all indexes
  await client.reindex(request, true);
}

loadData()
  .then(_ => console.log("Done"))
  .catch(error => console.error(error));