oa.batch_embeddings

Simplified interface for computing embeddings in bulk using OpenAI’s batch API.

This module provides a clean, reusable interface for generating embeddings from text segments using OpenAI’s batch API, handling the async nature of the API and providing status monitoring, error handling, and result aggregation.

Functions

compute_embeddings(segments[, model, ...])

Compute embeddings for text segments using OpenAI's batch API.

compute_embeddings_df(segments[, model])

Compute embeddings and return results as a pandas DataFrame.

Classes

BatchRequestCounts([completed, failed, total])

Counts of batch requests by status

BatchStatus()

Status constants for batch processing

EmbeddingsBatchProcess([segments, ...])

Manages the lifecycle of batch embedding requests.

ProcessingMall(*[, current, segments, ...])

Container for all stores needed during batch processing.

Exceptions

BatchError

Base exception for batch processing errors

exception oa.batch_embeddings.BatchError[source]

Bases: Exception

Base exception for batch processing errors

class oa.batch_embeddings.BatchRequestCounts(completed=0, failed=0, total=0)[source]

Bases: object

Counts of batch requests by status

class oa.batch_embeddings.BatchStatus[source]

Bases: object

Status constants for batch processing

classmethod is_success(status)[source]

Check if a status represents successful completion

Return type:

bool

classmethod is_terminal(status)[source]

Check if a status represents a terminal state

Return type:

bool

class oa.batch_embeddings.EmbeddingsBatchProcess(segments=None, processing_mall=None, *, model='text-embedding-3-small', batch_size=1000, poll_interval=5.0, max_polls=None, verbosity=1, keep_processing_info=False, dacc=None, logger=None, **embeddings_kwargs)[source]

Bases: object

Manages the lifecycle of batch embedding requests.

This class handles submitting batch requests to the OpenAI API, monitoring their status, retrieving results, and aggregating them. It can be used as a context manager for automatic cleanup.

aggregate_results()[source]

Aggregate all segments and embeddings from completed batches.

Return type:

tuple[list[str], list[list[float]]]

Returns:

Tuple of (all_segments, all_embeddings)

get_status_summary()[source]

Get a summary of batch statuses.

Return type:

dict[str, int]

Returns:

Dictionary with counts of batches in each status

property is_complete: bool

Check if batch processing is complete

property is_running: bool

Check if batch processing is currently running

monitor_batches()[source]

Monitor the status of all submitted batches until completion.

Return type:

None

property result: tuple[list[str], list[list[float]]] | None

Get the aggregated results if available

run()[source]

Execute the complete batch embedding workflow and return results.

This method submits batches, monitors their status until completion, and returns the aggregated results.

Return type:

tuple[list[str], list[list[float]]]

Returns:

Tuple of (all_segments, all_embeddings)

submit_batches()[source]

Submit all segment batches to the OpenAI API.

Return type:

dict[str, Batch]

Returns:

Dictionary mapping batch IDs to batch objects

class oa.batch_embeddings.ProcessingMall(*, current=None, segments=None, finished=None, erred=None, embeddings=None)[source]

Bases: Mapping

Container for all stores needed during batch processing.

The ProcessingMall contains five stores, all keyed by batch_id:

  • current: Batches that are currently being processed

  • segments: The text segments corresponding to each batch

  • finished: Completed batches

  • erred: Batches that encountered errors

  • embeddings: The computed embeddings for each batch

clear()[source]

Clear all stores

Return type:

None

is_complete()[source]

Check if processing is complete (no batches in current)

Return type:

bool

classmethod with_folder(rootdir, store_cls=<class 'dol.filesys.JsonFiles'>)[source]

Create a ProcessingMall with stores that persist to local files.

Parameters:

rootdir (str) – Directory where the stores will be saved

oa.batch_embeddings.compute_embeddings(segments, model='text-embedding-3-small', *, batch_size=1000, poll_interval=5.0, max_polls=None, verbosity=1, processing_mall=None, keep_processing_info=False, dacc=None, return_process=False, logger=None, **embeddings_kwargs)[source]

Compute embeddings for text segments using OpenAI’s batch API.

This function manages the complete lifecycle of batch embedding requests, from submitting batches to the API, monitoring their status, and aggregating the results.

Parameters:
  • segments (Union[list[str], dict[str, str]]) – Text segments to embed, either as a list or a dictionary

  • model (str) – OpenAI embedding model to use

  • batch_size (int) – Maximum number of segments per batch

  • poll_interval (float) – Seconds between status checks

  • max_polls (int | None) – Maximum number of status checks before timing out

  • verbosity (int) – Level of logging detail (0-2)

  • processing_mall (ProcessingMall | None) – Optional custom ProcessingMall

  • keep_processing_info (bool) – Whether to keep mall data after completion

  • dacc (OaDacc | None) – Optional custom OaDacc instance

  • return_process (bool) – If True, return the EmbeddingsBatchProcess object instead of results

  • logger (Logger | None) – Optional custom logger

  • **embeddings_kwargs – Additional parameters for embedding generation

Returns:

Tuple of (segments, embeddings) If return_process is True:

EmbeddingsBatchProcess object for further interaction

Return type:

tuple[list[str], list[list[float]]] | EmbeddingsBatchProcess

oa.batch_embeddings.compute_embeddings_df(segments, model='text-embedding-3-small', **kwargs)[source]

Compute embeddings and return results as a pandas DataFrame.

Parameters:
  • segments (Union[list[str], dict[str, str]]) – Text segments to embed

  • model (str) – OpenAI embedding model to use

  • **kwargs – Additional arguments passed to compute_embeddings

Return type:

pandas.DataFrame

Returns:

DataFrame with ‘segment’ and ‘embedding’ columns