FirstBatch

Usage

Python

FirstBatch is a Python package which you can install as:

pip install firstbatch

Then, FirstBatch core class can be imported as:

from firstbatch import FirstBatch

Async operations are also supported via:

from firstbatch import AsyncFirstBatch

Operations are identical for both classes, though the latter returns coroutines.

TypeScript

FirstBatch is an NPM package that can be installed via:

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

You can then import the FirstBatch class:

import {FirstBatch} from 'firstbatch';

Initialization

@dataclass
class Config(DataClassJsonMixin):
    """
    Configuration for the vector store.
    """
    batch_size: Optional[int] = None
    quantizer_train_size: Optional[int] = None
    quantizer_type: Optional[str] = None
    enable_history: Optional[bool] = None
    verbose: Optional[bool] = None

cfg = Config(batch_size=20, quantizer_train_size=100, quantizer_type="scalar",
enable_history=True, verbose=True)
personalized = FirstBatch(api_key=os.environ["FIRSTBATCH_API_KEY"], config=cfg)

To create a FirstBatch class, you need to provide an API key, along with optional configuration. The configuration fields are as follows for all SDKs:

• Embedding Size: A global embeddings size for FirstBatch class. Operations will use global embedding size if its not explicitly stated.

• Batch Size: Number of results returned from FirstBatch SDK.

• Quantizer Train Size: Training data size for quantizer. Note that Add a VectorDB relies on the train size and it will take longer to finish with increase train sizes.

• Quantizer Type: Quantizer type used to model distribution. Only accepts "scalar" currently, with "product" option soon to come.

• Enable History: If true, will keep track of items shown to user and will not re-display the same items within the same session.

• Verbose: Enables internal logs.

Note that all of these fields are optional and have their defaults.

Python

Here is an example of instantiating FirstBatch:

from firstbatch import FirstBatch, Config

cfg = Config(
    embedding_size=1536, 
    batch_size=20, 
    quantizer_train_size=100, 
    quantizer_type="scalar",
    enable_history=True, 
    verbose=True
)
api_key = os.environ["FIRSTBATCH_API_KEY"]
personalized = FirstBatch(api_key=api_key, config=cfg)

TypeScript

Here is an example of instantiating FirstBatch:

import {FirstBatch, FirstBatchConfig} from 'firstbatch';

const config: FirstBatchConfig = {
    embeddingSize: 1536,
    batchSize: 20,
    quantizerTrainSize: 100,
    quantizerType: 'scalar',
    enableHistory: true,
    verbose: true,
};
const apiKey = process.env.FIRSTBATCH_API_KEY;
const personalized = await FirstBatch.new(apiKey, config);

Methods

FirstBatch provides five fundamental methods:

:param vdbid: VectorDB ID of your choice, str
:param vs: VectorStore, object

• Add a VectorDB

• Create a Session

• Get User Embeddings

• Add a Signal

• Get a Batch

Add a VectorDB

Add a vectorDB of your choice to the instantiated FirstBatch client.

When you add a vector database, the sketching process can take up to 80 seconds the first time it runs. This operation is unique to each API_KEY and vdbid combination.

Changing either the API_KEY or vdbid results in the system treating it as a new vector database instance.

personalized.add_vdb("my_db", Pinecone(index, embedding_size=1536))

Python

add_vdb

:param vdbid: VectorDB ID of your choice, str
:param vs: VectorStore, object
:param embedding_size: Embedding size of your collection, if not will use class level embedding size, int

Adds VectorStore instance to Client.

Example run:

personalized.add_vdb("my_db", Pinecone(index))

TypeScript

addVdb

Parameters

• vdbid: VectorDB id of your choice

• vectorStore: a VectorStore instance

• embeddingSize: optional embedding size

Example

personalized.addVdb("my_db", Pinecone(index))

Create a Session

Creates a new session with the provided parameters & vector database ID. This method returns the sessionID; however, you can provide the sessionID with this method to create a persistent session.

When an algorithm other than SIMPLE or CUSTOM is used, it is registered as a FACTORY algorithm with the factoryId as the name of the algorithm.

Python

session

:param algorithm: Algorithm type of session, SIMPLE | CUSTOM | FACTORY types, AlgorithmLabel
:param vdbid: VectorStore id, str
:param session_id: Session id, Optional[str]
:param custom_id: Custom Algorithm ID, obtained from the dashboard. Used only with CUSTOM algorithm, Optional[str]

Creates a session. Session id is returned. If session_id is provided, FirstBatch will create a persistent session.

Example run with Simple Algorithm:

session = personalized.session(algorithm=AlgorithmLabel.SIMPLE, vdbid="my_db")

Example run with Factory Algorithm:

session = personalized.session(algorithm=AlgorithmLabel.UNIQUE_JOURNEYS, vdbid="my_db")

Example run with Custom Algorithm:

session = personalized.session(algorithm=AlgorithmLabel.CUSTOM, vdbid=vdbid, custom_id="7e0d17f5-da33-4534-b205-8873bc62a485")

TypeScript

session

Parameters

• algorithm: name of the algorithm

• vdbid: VectorDB id of your choice

• options: additional optional options

  • sessionId: to create a persistent session

  • customId: an identifier for the custom algorithm

Example

// Simple Algorithm 
await personalized.session("SIMPLE", "my_db");

// Factory Algorithm 
await personalized.session("SIMPLE", "my_db");

// Custom Algorithm
await personalized.session("CUSTOM", "my_db", {
    customId: 'some-id-here'
});

Get User Embeddings

Fetches the User Embeddings for a specific session.

Python

user_embeddings

:param session: SessionObject

Fetch user embeddings of session_id

Example run:

personalized.user_embeddings(session)

TypeScript

userEmbeddings

Parameters

• session session object

Example

await personalized.userEmbeddings(session);

Add a Signal

Add a signal to a session, indicating a user action.

Python

add_signal

:param session: SessionObject
:param user_action: UserAction
:param cid: str

Add a user signal.

Example run:

personalized.add_signal(session, UserAction(Signal.LIKE), cid)

Second Tab

addSignal

Parameters

• session session object

• userAction a User Action

• contentId id of a returned content from Get a Batch

Example

const userAction = new UserAction(Signals.LIKE);
await personalized.addSignal(session, userAction, contentId);

Get a Batch

Get new batch of data.

Python

batch

:param session: SessionObject
:param batch_size: batch size, if used, will override global batch size, Optional[int]

Get new batch of data.

Accepts **kwargs for operation type biased batch

"bias_vectors": List[List[float]]
"bias_weights": List[float]

Example run:

ids, batch = personalized.batch(session.data)

Randomly generating bias vectors:

starting_vectors = [vec.vector for vec in generate_vectors(1536, 5)]
starting_weights = [1.0] * 5
data = {"bias_vectors": starting_vectors, "bias_weights": starting_weights}

ids, batch = personalized.batch(session, **data)

TypeScript

batch

Parameters

• session session object

• options optional parameters

  • batchSize number of items in the batch. If undefined, will use the class-level value.

  • bias bias values for a biased-batch

    • vectors vectors for the biased batch

    • weights weights for the biased batch

Example

// a simple batch request
await personalized.batch(session);

// a biased batch of 20 items
await personalized.batch(session, {
    batchSize: 20,
    bias: {
        vectors,
        weights
    }
});