dspex

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

defmodule Dspy.Embeddings do
  @moduledoc """
  DSPy Embeddings retriever.

  This class retrieves the top-k most similar passages from a corpus using embedding-based similarity search.
  For large corpora, a FAISS index is built for fast approximate candidate retrieval, followed by exact
  re-ranking. For small corpora, brute-force search is used.
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "Embeddings"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

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

  ## Parameters

  - `corpus` (list(String.t()))
  - `embedder` (term())
  - `k` (integer() default: 5)
  - `callbacks` (term() default: None)
  - `cache` (boolean() default: False)
  - `brute_force_threshold` (integer() default: 20000)
  - `normalize` (boolean() default: True)
  """
  @spec new(list(String.t()), term(), list(term()), keyword()) ::
          {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(corpus, embedder, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)

    SnakeBridge.Runtime.call_class(
      __MODULE__,
      :__init__,
      [corpus, embedder] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  Python method `Embeddings._batch_forward`.

  ## Parameters

  - `queries` (list(String.t()))

  ## Returns

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

  @doc """
  Python method `Embeddings._build_faiss`.

  ## Returns

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

  @doc """
  Python method `Embeddings._faiss_search`.

  ## Parameters

  - `query_embeddings` (term())
  - `num_candidates` (integer())

  ## Returns

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

  @doc """
  Python method `Embeddings._normalize`.

  ## Parameters

  - `embeddings` (term())

  ## Returns

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

  @doc """
  Python method `Embeddings._rerank_and_predict`.

  ## Parameters

  - `q_embeds` (term())
  - `candidate_indices` (term())

  ## Returns

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

  @doc """
  Search for the top-k passages most similar to the query.



  ## Parameters

  - `query` - The search query string (type: `String.t()`)

  ## Returns

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

  @doc """
  Create an Embeddings instance from a saved index.

  This is the recommended way to load saved embeddings as it creates a new
  instance without unnecessarily computing embeddings.

  ## Parameters

  - `path` - Directory path where the embeddings were saved
  - `embedder` - The embedder function to use for new queries

  ## Examples

      ```python
      # Save embeddings
      embeddings = Embeddings(corpus, embedder)
      embeddings.save("./saved_embeddings")

      # Load embeddings later
      loaded_embeddings = Embeddings.from_saved("./saved_embeddings", embedder)
      ```

  ## Returns

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

  @doc """
  Load the embeddings index from disk into the current instance.



  ## Parameters

  - `path` - Directory path where the embeddings were saved
  - `embedder` - The embedder function to use for new queries

  ## Returns

  Returns `self`. Returns self for method chaining

  ## Raises

  - `File.Error` - If the save directory or required files don't exist
  - `ArgumentError` - If the saved config is invalid or incompatible
  """
  @spec load(SnakeBridge.Ref.t(), String.t(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def load(ref, path, embedder, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :load, [path, embedder], opts)
  end

  @doc """
  Save the embeddings index to disk.

  This saves the corpus, embeddings, FAISS index (if present), and configuration
  to allow for fast loading without recomputing embeddings.

  ## Parameters

  - `path` - Directory path where the embeddings will be saved

  ## Returns

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