API Reference

darca-embeddings

Modular, backend-agnostic interface for generating text embeddings. Default backend: OpenAI

Exports:

• EmbeddingClient: Unified interface for embeddings

• BaseEmbeddingClient: Abstract base for all embeddings backends

• OpenAIEmbeddingClient: Concrete backend using OpenAI Embedding API

• All custom exceptions

class darca_embeddings.BaseEmbeddingClient

Bases: ABC

Abstract base class for Embedding providers.

Implementations of this class must provide methods to generate embeddings from text input, typically by interacting with an external model or service.

abstractmethod get_embedding(text: str) → list[float]

Generate a vector embedding for a single piece of text.

Parameters:

text (str) – The input string to be embedded.

Returns:

A floating-point vector (list) representation of the input text.

Return type:

list[float]

Raises:

EmbeddingException – If something goes wrong with the embedding request.

get_embeddings(texts: list[str]) → list[list[float]]

Generate vector embeddings for a list of input texts.

By default, this method calls get_embedding() for each string in texts. Subclasses may override this method to provide more efficient batch processing.

Parameters:

texts (list[str]) – A list of input strings to embed.

Returns:

A list of embedding vectors, where each vector is a list of floats.

Return type:

list[list[float]]

Raises:

EmbeddingException – If something goes wrong while generating embeddings.

exception darca_embeddings.EmbeddingAPIKeyMissing(message, error_code=None, metadata=None, cause=None)

Bases: EmbeddingException

Raised when the API key is missing for the selected embeddings provider.

Typically occurs when the environment variable (e.g. OPENAI_API_KEY) is not set or is invalid.

add_note()

Exception.add_note(note) – add a note to the exception

args

log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class darca_embeddings.EmbeddingClient(backend: str = 'openai', **kwargs)

Bases: object

A unified client for generating embeddings using the darca pluggable backend system. Defaults to OpenAI.

This class wraps the functionality of various embedding providers behind a single interface. By specifying the backend argument, you can switch between multiple embeddings backends (e.g., OpenAI, HuggingFace, etc.).

Parameters:

• backend (str) – The backend provider to use, e.g. openai or huggingface.

• kwargs – Additional keyword arguments passed to the backend client’s constructor.

Raises:

EmbeddingException – If the chosen backend is not implemented or unsupported.

exception darca_embeddings.EmbeddingException(message, error_code=None, metadata=None, cause=None)

Bases: DarcaException

Base class for all darca-embeddings exceptions.

This exception can be extended or raised for any errors that occur within the darca-embeddings package.

add_note()

Exception.add_note(note) – add a note to the exception

args

log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception darca_embeddings.EmbeddingResponseError(message, error_code=None, metadata=None, cause=None)

Bases: EmbeddingException

Raised when an embeddings API request fails or returns malformed data.

For example, it may be raised if the network request times out, the API returns a non-200 status code, or the response is not in the expected format.

add_note()

Exception.add_note(note) – add a note to the exception

args

log_exception()

Logs the exception details using DarcaLogger. Always logs as an error because exceptions indicate failure.

to_dict()

Convert exception details to a dictionary.

Returns:

Dictionary representation of the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class darca_embeddings.OpenAIEmbeddingClient(model='text-embedding-ada-002')

Bases: BaseEmbeddingClient

Embedding provider that uses OpenAI’s Embedding API.

This client relies on the OPENAI_API_KEY environment variable for authentication. It uses the default model text-embedding-ada-002 unless otherwise specified.

Parameters:

model (str) – The OpenAI Embedding model to use.

Raises:

EmbeddingAPIKeyMissing – If the required API key environment variable is not found.

get_embedding(text: str) → list[float]

Generate an embedding for a single piece of text using OpenAI.

Parameters:

text (str) – The input text to be embedded.

Returns:

A list of floats representing the embedding of the text.

Return type:

list[float]

Raises:

EmbeddingResponseError –

• If the OpenAI API call fails or returns an unexpected format.

• If an unknown error occurs during processing.

get_embeddings(texts: list[str]) → list[list[float]]

Generate vector embeddings for a list of input texts.

By default, this method calls get_embedding() for each string in texts. Subclasses may override this method to provide more efficient batch processing.

Parameters:

texts (list[str]) – A list of input strings to embed.

Returns:

A list of embedding vectors, where each vector is a list of floats.

Return type:

list[list[float]]

Raises:

EmbeddingException – If something goes wrong while generating embeddings.