dspex

# Generated by SnakeBridge v0.16.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.1.2
# Python module: dspy
# Python class: Embedder

defmodule Dspy.Embedder do
  @moduledoc """
  DSPy embedding class.

  The class for computing embeddings for text inputs. This class provides a unified interface for both:

  1. Hosted embedding models (e.g. OpenAI's text-embedding-3-small) via litellm integration
  2. Custom embedding functions that you provide

  For hosted models, simply pass the model name as a string (e.g., "openai/text-embedding-3-small"). The class will use
  litellm to handle the API calls and caching.

  For custom embedding models, pass a callable function that:
  - Takes a list of strings as input.
  - Returns embeddings as either:
      - A 2D numpy array of float32 values
      - A 2D list of float32 values
  - Each row should represent one embedding vector

  ## Parameters

  - `model` - The embedding model to use. This can be either a string (representing the name of the hosted embedding model, must be an embedding model supported by litellm) or a callable that represents a custom embedding model.
  - `batch_size` - The default batch size for processing inputs in batches. Defaults to 200. (type: `integer()`)
  - `caching` - Whether to cache the embedding response when using a hosted model. Defaults to True. **kwargs: Additional default keyword arguments to pass to the embedding model. (type: `boolean()`)

  ## Examples

      Example 1: Using a hosted model.

      ```python
      import dspy

      embedder = dspy.Embedder("openai/text-embedding-3-small", batch_size=100)
      embeddings = embedder(["hello", "world"])

      assert embeddings.shape == (2, 1536)
      ```

      Example 2: Using any local embedding model, e.g. from https://huggingface.co/models?library=sentence-transformers.

      ```python
      # pip install sentence_transformers
      import dspy
      from sentence_transformers import SentenceTransformer

      # Load an extremely efficient local model for retrieval
      model = SentenceTransformer("sentence-transformers/static-retrieval-mrl-en-v1", device="cpu")

      embedder = dspy.Embedder(model.encode)
      embeddings = embedder(["hello", "world"], batch_size=1)

      assert embeddings.shape == (2, 1024)
      ```

      Example 3: Using a custom function.

      ```python
      import dspy
      import numpy as np

      def my_embedder(texts):
      return np.random.rand(len(texts), 10)

      embedder = dspy.Embedder(my_embedder)
      embeddings = embedder(["hello", "world"], batch_size=1)

      assert embeddings.shape == (2, 10)
      ```
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "Embedder"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initialize self.  See help(type(self)) for accurate signature.

  ## Parameters

  - `model` (String.t() | term())
  - `batch_size` (integer() default: 200)
  - `caching` (boolean() default: True)
  - `kwargs` (%{optional(String.t()) => term()})
  """
  @spec new(String.t() | term(), list(term()), keyword()) ::
          {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(model, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [model] ++ List.wrap(args), opts)
  end

  @doc """
  Python method `Embedder._postprocess`.

  ## Parameters

  - `embeddings_list` (term())
  - `is_single_input` (term())

  ## Returns

  - `term()`
  """
  @spec _postprocess(SnakeBridge.Ref.t(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def _postprocess(ref, embeddings_list, is_single_input, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :_postprocess, [embeddings_list, is_single_input], opts)
  end

  @doc """
  Python method `Embedder._preprocess`.

  ## Parameters

  - `inputs` (term())
  - `batch_size` (term() default: None)
  - `caching` (term() default: None)
  - `kwargs` (term())

  ## Returns

  - `term()`
  """
  @spec _preprocess(SnakeBridge.Ref.t(), term(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def _preprocess(ref, inputs, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_method(ref, :_preprocess, [inputs] ++ List.wrap(args), opts)
  end

  @doc """
  Python method `Embedder.acall`.

  ## Parameters

  - `inputs` (term())
  - `batch_size` (term() default: None)
  - `caching` (term() default: None)
  - `kwargs` (term())

  ## Returns

  - `term()`
  """
  @spec acall(SnakeBridge.Ref.t(), term(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def acall(ref, inputs, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_method(ref, :acall, [inputs] ++ List.wrap(args), opts)
  end
end