Embed Module¶

The Embed module provides a simple, function-like API for text embeddings with support for structured parameter configuration.

Core Classes¶

Embed Client¶

class lexilux.embed.Embed(*, base_url, api_key=None, model=None, timeout_s=60.0, headers=None, proxies=None, pool_size=10)[source]¶

Bases: AsyncClientMixin

Embedding API client with connection pooling.

Provides a simple, function-like API for text embeddings. Uses connection pooling for improved performance in high-throughput scenarios.

Examples

>>> embed = Embed(base_url="https://api.example.com/v1", api_key="key", model="text-embedding-ada-002")
>>> result = embed("Hello, world!")
>>> vector = result.vectors  # List[float]

>>> result = embed(["text1", "text2"])
>>> vectors = result.vectors  # List[List[float]]

>>> # Context manager for proper resource cleanup
>>> with Embed(base_url="...", api_key="key") as embed:
...     result = embed("Hello")

__init__(*, base_url, api_key=None, model=None, timeout_s=60.0, headers=None, proxies=None, pool_size=10)[source]¶

Initialize Embed client.

Parameters:

base_url (str) – Base URL for the API (e.g., “https://api.openai.com/v1”).
api_key (str | None) – API key for authentication (optional if provided in headers).
model (str | None) – Default model to use (can be overridden in __call__).
timeout_s (float) – Request timeout in seconds.
headers (dict[str, str] | None) – Additional headers to include in requests.
proxies (dict[str, str] | None) – Optional proxy configuration dict (e.g., {“http”: “http://proxy:port”}). If None, uses environment variables (HTTP_PROXY, HTTPS_PROXY). To disable proxies, pass {}.
pool_size (int) – Connection pool size for HTTP adapter (default: 10, max: 100).

Raises:

ValueError – If pool_size is not in range [1, 100].

__call__(input, *, model=None, dimensions=None, encoding_format=None, user=None, params=None, extra=None, return_raw=False)[source]¶

Make an embedding request.

Supports both direct parameter passing (backward compatible) and EmbedParams dataclass for structured configuration.

Parameters:

input (str | Sequence[str]) – Single text string or sequence of text strings.
model (str | None) – Model to use (overrides default).
dimensions (int | None) – Number of dimensions for output embeddings. Only supported in some models (e.g., text-embedding-3-*). Default: None (use model default)
encoding_format (Literal['float', 'base64'] | None) – Format to return embeddings. “float” (default) or “base64”. Some providers may support additional formats.
user (str | None) – Unique identifier for end-user (for monitoring/rate limiting).
params (EmbedParams | None) – EmbedParams dataclass instance. If provided, overrides individual parameters above. Useful for structured configuration.
extra (dict[str, Any] | None) – Additional custom parameters for non-standard providers. Merged with params if both are provided.
return_raw (bool) – Whether to include full raw response.

Returns:

EmbedResult with vectors and usage.

Raises:

requests.RequestException – On network or HTTP errors.
ValueError – On invalid input or response format.

Return type:

EmbedResult

Examples

Basic usage (backward compatible): >>> result = embed(“Hello”, dimensions=512)

Using EmbedParams: >>> from lexilux import EmbedParams >>> params = EmbedParams(dimensions=512, encoding_format=”float”) >>> result = embed(“Hello”, params=params)

Combining params and extra: >>> result = embed(“Hello”, params=params, extra={“custom”: “value”})

async acall(input, *, model=None, dimensions=None, encoding_format=None, user=None, params=None, extra=None, return_raw=False)[source]¶

Make an async embedding request.

This is the async version of __call__(). All parameters and behavior are identical to the sync version.

Parameters:

input (str | Sequence[str]) – Single text string or sequence of text strings.
model (str | None) – Model to use (overrides default).
dimensions (int | None) – Number of dimensions for output embeddings.
encoding_format (Literal['float', 'base64'] | None) – Format to return embeddings.
user (str | None) – Unique identifier for end-user.
params (EmbedParams | None) – EmbedParams dataclass instance.
extra (dict[str, Any] | None) – Additional custom parameters.
return_raw (bool) – Whether to include full raw response.

Returns:

EmbedResult with vectors and usage.

Return type:

EmbedResult

Examples

>>> result = await embed.acall("Hello")
>>> vector = result.vectors

close()[source]¶

Close the sync session and release resources.

Should be called when done with the client, or use context manager.

Result Models¶

class lexilux.embed.EmbedResult(*, vectors, usage, raw=None)[source]¶

Bases: ResultBase

Embedding result.

The vectors field contains: - Single Vector (List[float]) when input is a single string - List[Vector] (List[List[float]]) when input is a sequence of strings

vectors¶: Embedding vector(s).

usage¶: Usage statistics.

raw¶: Raw API response.

Examples

>>> result = embed("Hello")
>>> vector = result.vectors  # List[float]

>>> result = embed(["Hello", "World"])
>>> vectors = result.vectors  # List[List[float]]

__init__(*, vectors, usage, raw=None)[source]¶

Initialize EmbedResult.

Parameters:

vectors (list[float] | list[list[float]]) – Embedding vector(s).
usage (Usage) – Usage statistics.
raw (dict[str, Any] | None) – Raw API response.

__repr__()[source]¶

Return string representation.

Parameter Configuration¶

class lexilux.embed_params.EmbedParams(dimensions=None, encoding_format='float', user=None, extra=None)[source]

Bases: object

Standard parameters for embedding requests.

This class defines the most commonly used parameters for OpenAI-compatible embedding APIs. All parameters are optional and have sensible defaults.

dimensions

The number of dimensions the resulting output embeddings should have. Only supported in some models (e.g., text-embedding-3-*). For example, text-embedding-3-large can output embeddings with dimensions from 256 up to 3072. Default: None (use model’s default)

Type:: int | None

encoding_format

The format to return the embeddings in. Can be either “float” (default) or “base64”. Some providers may support additional formats. Default: “float”

Type:: Literal[‘float’, ‘base64’]

user

A unique identifier representing your end-user, which can help providers to monitor and detect abuse. This is useful for tracking and rate limiting. Default: None

Type:: str | None

extra

Additional custom parameters for OpenAI-compatible servers that may accept non-standard parameters. These will be merged into the request payload. Useful for provider-specific features. Default: None (empty dict)

Type:: dict[str, Any] | None

Examples

Basic usage with defaults: >>> params = EmbedParams() >>> # encoding_format=”float”, etc.

Custom dimensions: >>> params = EmbedParams(dimensions=512)

With custom encoding format: >>> params = EmbedParams(encoding_format=”base64”)

With custom parameters: >>> params = EmbedParams( … dimensions=256, … extra={“custom_param”: “value”} … )

dimensions: int | None = None

encoding_format: Literal['float', 'base64'] = 'float'

user: str | None = None

extra: dict[str, Any] | None = None

to_dict(exclude_none=True)[source]

Convert parameters to dictionary for API request.

Parameters:: exclude_none (bool) – Whether to exclude None values from the output. Default: True
Returns:: Dictionary of parameters ready for API request.
Return type:: dict[str, Any]

Examples

>>> params = EmbedParams(dimensions=512, encoding_format="float")
>>> params.to_dict()
{'dimensions': 512, 'encoding_format': 'float'}

__init__(dimensions=None, encoding_format='float', user=None, extra=None)