firstbatchxyz / firstbatch-sdk-ts

TypeScript SDK for FirstBatch: Real-time Personalization using VectorDBs.

FirstBatch SDK

FirstBatch SDK provides an interface for integrating vector databases and powering personalized AI experiences in your application.

• Seamlessly manage user sessions with persistent IDs or temporary sessions.
• Send signal actions like likes, clicks, etc. to update user embeddings in real-time.
• Fetch personalized batches of data tailored to each user's embeddings.
• Support for multiple vector database integrations: Pinecone, Weaviate, etc.
• Built-in algorithms for common personalization use cases.

For more information, see the User Embedding Guide or the SDK Documentation.

Installation

Install the package from NPM:

npm install firstbatch  # npm
yarn add firstbatch     # yarn
pnpm add firstbatch     # pnpm

Usage

FirstBatch SDK is used together with an existing vector store, where you register the vector store to our SDK and then create personalization sessions from it.

Adding a Client

First, initialize a Vector Database of your choice; our SDK supports:

• Pinecone
• Weaviate
• Typesense (work in progress)
• Supabase (work in progress)

Let us go over an example using Pinecone.

import {Pinecone as PineconeClient} from '@pinecone-database/pinecone';
import {Pinecone, FirstBatch, Signals} from 'firstbatch';

// create Pinecone client
const pinecone = new PineconeClient({apiKey: 'pinecone-api-key', environment: 'pinecone-env'});
await pinecone.describeIndex('index-name');
const index = pinecone.index('index-name');

Then, create a Vector Store with this index and pass it in the FirstBatch SDK.

// create SDK
const personalized = await FirstBatch.new('firstbatch-api-key');

// add vector store to SDK
const vectorStore = new Pinecone(index);
const vdbid = 'pinecone-example-db';
await personalized.addVectorStore(vdbid, vectorStore);

Personalization

Now, we can create a session with an algorithm that suits our use-case, and provide personalization to our users.

// create a session
const session = personalized.session('ALGORITHM_NAME', vdbid);

// make recommendations
const [ids, batch] = personalized.batch(session);

Suppose that the user has liked the first content from the batch above. We can provide personalization over this as follows:

// the user liked the first content of the previous batch
const userPick = ids[0];

// signal this to the session
personalized.addSignal(sessionId, Signals.LIKE, userPick);

Here, LIKE signal is one of the many preset signals provided by our SDK. You can also define your own signals:

import type {Signal} from 'firstbatch';

const mySignal: Signal = {label: 'SOME_USER_ACTION', weight: 0.5};

Building

Install the dependencies:

bun install

Then, build everything with:

bun run build
bun b # alternative

Note

If you get an error like "expected content key ... to exist" simply delete the .parcel-cache folder and build again.

Testing

Run all tests via:

bun run test
bun t # alternative

Bun will look for .env.test during the tests.

Styling

Check formatting:

bun format

Lint everything:

bun lint

firstbatch-sdk-ts's Issues

Better typing needed for `batch`

Instead of:

[string[], QueryMetadata[]]

make a single type such as:

{id: string, metadata: QueryMetadata}[]

`getAlgorithm` is called on each Signal

Pinecone1.0.x ~ Bun Integration

See issue here: pinecone-io/pinecone-ts-client#141

Refactor metadatas

CJS vs MJS issue with `loglevel` package

Wrong algorithm state

It seems to be possible sometimes that your state within the algorithm is incorrect, w.r.t. DFA. First found at https://github.com/erhant/leet-assistant

Redundant existence checks during `addVdb`

addVdb checks if the given vectorDB with vdbid exists via an API call. Sometimes we can be SURE that it exists, i.e. we have done the setup and this thing works in a serverless function etc. so we dont have to check for existence in those cases.

It is possible to bypass this by doing:

sdk.store[vdbid] = vectorStore;

instead of

await sdk.addVdb(vdbid, vectorStore);

which saves making an api call.

We can make this clear to the user via docs, perhaps?

Add `post` return data types within `client/client.ts`

@anilaltuner we should check the api endpoint code for this

Refactor `BatchXXX` classes

rename `batchType` field into `batch_type` for `update_state` endpoint data

`addSignal` return type

• Currently, it returns response.success
• In Python, it does not return anything
• It should perhaps return the new state of DFA for debugging purposes?

Notify if `addVdb` was not called and thus `vectorStore` is undefined

Otherwise you most likely get Cannot read properties of undefined (reading 'embeddingSize') error.

Weaviate integration tests

Due to a hidden bug from before, the tests were passing although there were errors within Weaviate integration related to metadata. That is hot-fixed now, but requires further care.

Do not use Parcel for building

Give better error response for `addSignal` instead of `ok = false`

Pinecone metadatas

It may be the case that we are setting the metadata wrong, instead of an object like {id: string, metadata: any} we might have {id: string, metadata: {id: string, data: any}} instead.

Within `addSignal`, must `addHistory` on success only

This one in particular:

 if (this.enableHistory) {
      await this.addHistory(session, [contentId]);
    }

should respect resp.success

Allow generic types for `QueryMetadata`

This type should probably given to the SDK itself, not just the function.

Do not use class objects in API

For example UserAction is one such thing.