https://github.com/firstbatchxyz/firstbatch-sdk-ts
TypeScript SDK for FirstBatch: Real-time Personalization using VectorDBs.
https://github.com/firstbatchxyz/firstbatch-sdk-ts
personalization pinecone sdk typesense vector-database vectordb weaviate
Last synced: about 1 year ago
JSON representation
TypeScript SDK for FirstBatch: Real-time Personalization using VectorDBs.
- Host: GitHub
- URL: https://github.com/firstbatchxyz/firstbatch-sdk-ts
- Owner: firstbatchxyz
- License: mit
- Created: 2023-10-16T10:22:48.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-02-16T08:42:20.000Z (over 2 years ago)
- Last Synced: 2025-04-15T09:52:37.753Z (about 1 year ago)
- Topics: personalization, pinecone, sdk, typesense, vector-database, vectordb, weaviate
- Language: TypeScript
- Homepage: https://firstbatch.xyz/
- Size: 177 KB
- Stars: 5
- Watchers: 3
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
FirstBatch SDK
FirstBatch SDK provides an interface for integrating vector databases and powering personalized AI experiences in your application.
- [x] Seamlessly manage user sessions with persistent IDs or temporary sessions.
- [x] Send signal actions like likes, clicks, etc. to update user embeddings in real-time.
- [x] Fetch personalized batches of data tailored to each user's embeddings.
- [x] Support for multiple vector database integrations: Pinecone, Weaviate, etc.
- [x] Built-in algorithms for common personalization use cases.
For more information, see the [User Embedding Guide](https://firstbatch.gitbook.io/user-embeddings/) or the [SDK Documentation](https://firstbatch.gitbook.io/firstbatch-sdk/).
## Installation
Install the package from NPM:
```sh
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:
- [x] [Pinecone](https://www.npmjs.com/package/@pinecone-database/pinecone)
- [x] [Weaviate](https://www.npmjs.com/package/weaviate-ts-client)
- [ ] [Typesense](https://www.npmjs.com/package/typesense) (work in progress)
- [ ] [Supabase](https://www.npmjs.com/package/@supabase/supabase-js) (work in progress)
Let us go over an example using Pinecone.
```ts
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.
```ts
// 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.
```ts
// 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:
```ts
// 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:
```ts
import type {Signal} from 'firstbatch';
const mySignal: Signal = {label: 'SOME_USER_ACTION', weight: 0.5};
```
## Building
Install the dependencies:
```bash
bun install
```
Then, build everything with:
```bash
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:
```bash
bun run test
bun t # alternative
```
Bun will look for `.env.test` during the tests.
## Styling
Check formatting:
```sh
bun format
```
Lint everything:
```sh
bun lint
```