dspex

# Generated by SnakeBridge v0.13.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.1.2
# Python module: dspy.dsp.utils.settings
# Python class: Settings

defmodule Dspy.Dsp.Utils.Settings.Settings do
  @moduledoc """
  A singleton class for DSPy configuration settings.

  Thread-safe global configuration.
  - 'configure' can be called by only one 'owner' thread (the first thread that calls it).
  - Other threads see the configured global values from 'main_thread_config'.
  - 'context' sets thread-local overrides. These overrides propagate to threads spawned
    inside that context block, when (and only when!) using a ParallelExecutor that copies overrides.

    1. Only one unique thread (which can be any thread!) can call dspy.configure.
    2. It affects a global state, visible to all. As a result, user threads work, but they shouldn't be
       mixed with concurrent changes to dspy.configure from the "main" thread.
       (TODO: In the future, add warnings: if there are near-in-time user-thread reads followed by .configure calls.)
    3. Any thread can use dspy.context. It propagates to child threads created with DSPy primitives: Parallel, asyncify, etc.
  """
  def __snakebridge_python_name__, do: "dspy.dsp.utils.settings"
  def __snakebridge_python_class__, do: "Settings"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

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

  ## Parameters

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

  @doc """
  Python method `Settings._ensure_configure_allowed`.

  ## Returns

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

  @doc """
  Python method `Settings.configure`.

  ## Parameters

  - `kwargs` (term())

  ## Returns

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

  @doc """
  Context manager for temporary configuration changes at the thread level.

  Does not affect global configuration. Changes only apply to the current thread.
  If threads are spawned inside this block using ParallelExecutor, they will inherit these overrides.

  ## Parameters

  - `kwargs` (term())

  ## Returns

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

  @doc """
  Python method `Settings.copy`.

  ## Returns

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

  @doc """
  Python method `Settings.get`.

  ## Parameters

  - `key` (term())
  - `default` (term() default: None)

  ## Returns

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

  @doc """
  Load the settings from a file using cloudpickle.



  ## Parameters

  - `path` - The file path to load the settings from.

  ## Returns

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

  @doc """
  Save the settings to a file using cloudpickle.



  ## Parameters

  - `path` - The file path to save the settings to.
  - `modules_to_serialize` - A list of modules to serialize with cloudpickle's `register_pickle_by_value`. If None, then no modules will be registered for serialization. (type: `list or None`)
  - `exclude_keys` - A list of keys to exclude during saving. (type: `list or None`)

  ## Returns

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

  @spec _instance(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _instance(ref) do
    SnakeBridge.Runtime.get_attr(ref, :_instance)
  end

  @spec config(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def config(ref) do
    SnakeBridge.Runtime.get_attr(ref, :config)
  end

  @spec lock(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def lock(ref) do
    SnakeBridge.Runtime.get_attr(ref, :lock)
  end
end