NLUDB Typescript Client Library

NLUDB is a cloud-hosted database that helps developers get work done with natural language content.

NLUDB is currently in a closed beta. If you are interested in joining, please sign up at https://www.nludb.com

Installing

npm install nludb --save

Using

Initialization

Sign up for an account at https://www.nludb.com to get your API key. Then use it to initialize your client library:

import NLUDB from '@nludb/client';
const nludb = new NLUDB(api_key);

Embedding Indices

An Embedding Index is a persistent, read-optimized index over an embedded space. Once an index is created, you can search for similar items within that embedding space.

const index = await nludb.createIndex({
  name: 'Question Answering Index',
  model: EmbeddingModels.QA,
  upsert: true,
});

await index.insert({ value: 'Armadillo shells are bulletproof.' });
await index.insert({ value: 'Dolphins sleep with one eye open.' });
await index.insert({ value: 'Alfred Hitchcock was frightened of eggs.' });
await index.insert({
  value: 'Jonathan can help you with new employee onboarding',
});
await index.insert({ value: 'The code for the New York office is 1234' });

let task = await index.embed();
await task.wait();

const results = await index.search({
  query: 'Who should I talk to about new employee setup?',
});

Developing

This library was made with the Typescript Starter. Many of the development instructions here are copy-pasted from their README.

To start working, run the watch:build task using npm or yarn.

npm run watch:build

In another terminal tab/window, run the watch:test task:

npm run watch:test

These watch tasks make development much faster and more interactive. They're particularly helpful for TDD/BDD workflows.

These watch tasks will build and watch the entire project for changes (to both the library source files and test source files). As you develop, you can add tests for new functionality – which will initially fail – before developing the new functionality. Each time you save, any changes will be rebuilt and retested.

Since only changed files are rebuilt and retested, this workflow remains fast even for large projects.

Enable stronger type checking (recommended)

To make getting started easier, the default tsconfig.json is using a very flexible configuration. This will allow you to get started without many warnings from Typescript.

To enable additional Typescript type checking features (a good idea for mission-critical or large projects), review the commented-out lines in your typescript compiler options.

Auto-fix and format project

To automatically fix eslint and prettier formatting issues, run:

npm run fix

View test coverage

To generate and view test coverage, run:

npm run cov

This will create an HTML report of test coverage – source-mapped back to Typescript – and open it in your default browser.

Generate your API docs

The src folder is analyzed and documentation is automatically generated using TypeDoc.

npm run doc

This command generates API documentation for your library in HTML format and opens it in a browser.

Since types are tracked by Typescript, there's no need to indicate types in JSDoc format. For more information, see the TypeDoc documentation.

To generate and publish your documentation to GitHub Pages use the following command:

npm run doc:publish

Once published, your documentation should be available at the proper GitHub Pages URL for your repo. See typescript-starter's GitHub Pages for an example.

For more advanced documentation generation, you can provide your own TypeDoc theme, or build your own documentation using the JSON TypeDoc export:

npm run doc:json

Bump version, update changelog, commit, & tag release

It's recommended that you install commitizen to make commits to your project.

npm install -g commitizen

# commit your changes:
git cz

This project is tooled for conventional changelog to make managing releases easier. See the standard-version documentation for more information on the workflow, or CHANGELOG.md for an example.

# bump package.json version, update CHANGELOG.md, git tag the release
npm run version

You may find a tool like wip helpful for managing work in progress before you're ready to create a meaningful commit.

One-step publish preparation script

Bringing together many of the steps above, this repo includes a one-step release preparation command.

# Prepare a standard release:
npm run prepare-release

This command runs the following tasks:

• hard-reset: cleans the repo by removing all untracked files and resetting --hard to the latest commit. (Note: this could be destructive.)
• test: build and fully test the project
• doc:html: generate the latest version of the documentation
• doc:publish: publish the documentation to GitHub Pages
• version: bump package.json version, update CHANGELOG.md, and git tag the release

When the script finishes, it will log the final command needed to push the release commit to the repo and publish the package on the npm registry:

git push --follow-tags origin master; npm publish --access=public

Look over the release if you'd like, then execute the command to publish everything.

You can also prepare a non-standard release:

# Or a non-standard release:

# Reset the repo to the latest commit and build everything
npm run hard-reset && npm run test && npm run cov:check && npm run doc:html

# Then version it with standard-version options. e.g.:
# don't bump package.json version
npm run version -- --first-release

# Other popular options include:

# PGP sign it:
# $ npm run version -- --sign

# alpha release:
# $ npm run version -- --prerelease alpha

# And don't forget to push the docs to GitHub pages:
npm run doc:publish