firstbatch sdk ts

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