Comment on page
FirstBatch

Usage
Python
TypeScript
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. 
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
TypeScript
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)
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
TypeScript
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))
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
TypeScript
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")
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
TypeScript
user_embeddings
:param session: SessionObject
Fetch user embeddings of session_id
Example run:
personalized.user_embeddings(session)
userEmbeddings
Parameters
session session object
Example
await personalized.userEmbeddings(session);
Add a Signal
Add a signal to a session, indicating a user action.
Python
Second Tab
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)
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
TypeScript
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)
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
    }
});
​
User-Centric Promoted Content
Next - Modules
Algorithms
Last modified 17d ago