dspex

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

defmodule Dspy.Dsp.Utils do
  @moduledoc """
  Submodule bindings for `dspy.dsp.utils`.

  ## Version

  - Requested: 3.1.2
  - Observed at generation: 3.1.2

  ## Runtime Options

  All functions accept a `__runtime__` option for controlling execution behavior:

      Dspy.Dsp.Utils.some_function(args, __runtime__: [timeout: 120_000])

  ### Supported runtime options

  - `:timeout` - Call timeout in milliseconds (default: 120,000ms / 2 minutes)
  - `:timeout_profile` - Use a named profile (`:default`, `:ml_inference`, `:batch_job`, `:streaming`)
  - `:stream_timeout` - Timeout for streaming operations (default: 1,800,000ms / 30 minutes)
  - `:session_id` - Override the session ID for this call
  - `:pool_name` - Target a specific Snakepit pool (multi-pool setups)
  - `:affinity` - Override session affinity (`:hint`, `:strict_queue`, `:strict_fail_fast`)

  ### Timeout Profiles

  - `:default` - 2 minute timeout for regular calls
  - `:ml_inference` - 10 minute timeout for ML/LLM workloads
  - `:batch_job` - Unlimited timeout for long-running jobs
  - `:streaming` - 2 minute timeout, 30 minute stream_timeout

  ### Example with timeout override

      # For a long-running ML inference call
      Dspy.Dsp.Utils.predict(data, __runtime__: [timeout_profile: :ml_inference])

      # Or explicit timeout
      Dspy.Dsp.Utils.predict(data, __runtime__: [timeout: 600_000])

      # Route to a pool and enforce strict affinity
      Dspy.Dsp.Utils.predict(data, __runtime__: [pool_name: :strict_pool, affinity: :strict_queue])

  See `SnakeBridge.Defaults` for global timeout configuration.

  """

  @doc false
  def __snakebridge_python_name__, do: "dspy.dsp.utils"
  @doc false
  def __snakebridge_library__, do: "dspy"

  @doc """
  Python binding for `dspy.dsp.utils.batch`.

  ## Parameters

  - `group` (term())
  - `bsize` (term())
  - `provide_offset` (term() default: False)

  ## Returns

  - `term()`
  """
  @spec batch(term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec batch(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec batch(term(), term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec batch(term(), term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def batch(group, bsize) do
    SnakeBridge.Runtime.call(__MODULE__, :batch, [group, bsize], [])
  end

  def batch(group, bsize, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :batch, [group, bsize], opts)
  end

  def batch(group, bsize, provide_offset) do
    SnakeBridge.Runtime.call(__MODULE__, :batch, [group, bsize, provide_offset], [])
  end

  def batch(group, bsize, provide_offset, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :batch, [group, bsize, provide_offset], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.create_directory`.

  ## Parameters

  - `path` (term())

  ## Returns

  - `term()`
  """
  @spec create_directory(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def create_directory(path, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :create_directory, [path], opts)
  end

  @doc """
  From Raymond Hettinger

  https://twitter.com/raymondh/status/944125570534621185
  Since Python 3.6 Dict are ordered
  Benchmark: https://gist.github.com/peterbe/67b9e40af60a1d5bcb1cfb4b2937b088

  ## Parameters

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

  ## Returns

  - `list(String.t())`
  """
  @spec deduplicate(list(String.t()), keyword()) ::
          {:ok, list(String.t())} | {:error, Snakepit.Error.t()}
  def deduplicate(seq, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :deduplicate, [seq], opts)
  end

  @doc """
  Python module attribute `dspy.dsp.utils.DEFAULT_CONFIG`.

  ## Returns

  - `Dspy.Dsp.Utils.Utils.Dotdict.t()`
  """
  @spec default_config() :: {:ok, Dspy.Dsp.Utils.Utils.Dotdict.t()} | {:error, Snakepit.Error.t()}
  def default_config() do
    SnakeBridge.Runtime.get_module_attr(__MODULE__, "DEFAULT_CONFIG")
  end

  @doc """
  Python binding for `dspy.dsp.utils.DPR_normalize`.

  ## Parameters

  - `text` (term())

  ## Returns

  - `term()`
  """
  @spec dpr_normalize(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def dpr_normalize(text, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, "DPR_normalize", [text], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.DPR_tokenize`.

  ## Parameters

  - `text` (term())

  ## Returns

  - `term()`
  """
  @spec dpr_tokenize(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def dpr_tokenize(text, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, "DPR_tokenize", [text], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.file_tqdm`.

  ## Parameters

  - `file` (term())

  ## Returns

  - `term()`
  """
  @spec file_tqdm(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def file_tqdm(file, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :file_tqdm, [file], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.flatten`.

  ## Parameters

  - `data_list` (term())

  ## Returns

  - `term()`
  """
  @spec flatten(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def flatten(data_list, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :flatten, [data_list], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.groupby_first_item`.

  ## Parameters

  - `lst` (term())

  ## Returns

  - `term()`
  """
  @spec groupby_first_item(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def groupby_first_item(lst, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :groupby_first_item, [lst], opts)
  end

  @doc """
  Collect data into fixed-length chunks or blocks

  Example: grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx"
    Source: https://docs.python.org/3/library/itertools.html#itertools-recipes

  ## Parameters

  - `iterable` (term())
  - `n` (term())
  - `fillvalue` (term() default: None)

  ## Returns

  - `term()`
  """
  @spec grouper(term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec grouper(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec grouper(term(), term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec grouper(term(), term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def grouper(iterable, n) do
    SnakeBridge.Runtime.call(__MODULE__, :grouper, [iterable, n], [])
  end

  def grouper(iterable, n, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :grouper, [iterable, n], opts)
  end

  def grouper(iterable, n, fillvalue) do
    SnakeBridge.Runtime.call(__MODULE__, :grouper, [iterable, n, fillvalue], [])
  end

  def grouper(iterable, n, fillvalue, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :grouper, [iterable, n, fillvalue], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.has_answer`.

  ## Parameters

  - `tokenized_answers` (term())
  - `text` (term())

  ## Returns

  - `term()`
  """
  @spec has_answer(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def has_answer(tokenized_answers, text, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :has_answer, [tokenized_answers, text], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.int_or_float`.

  ## Parameters

  - `val` (term())

  ## Returns

  - `term()`
  """
  @spec int_or_float(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def int_or_float(val, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :int_or_float, [val], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.lengths2offsets`.

  ## Parameters

  - `lengths` (term())

  ## Returns

  - `term()`
  """
  @spec lengths2offsets(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def lengths2offsets(lengths, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :lengths2offsets, [lengths], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.load_batch_backgrounds`.

  ## Parameters

  - `args` (term())
  - `qids` (term())

  ## Returns

  - `term()`
  """
  @spec load_batch_backgrounds(term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def load_batch_backgrounds(args, qids, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :load_batch_backgrounds, [args, qids], opts)
  end

  @doc """
  Returns each occurrence of an answer as (offset, endpos) in terms of *characters*.

  ## Parameters

  - `tokenized_answers` (term())
  - `text` (term())

  ## Returns

  - `term()`
  """
  @spec locate_answers(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def locate_answers(tokenized_answers, text, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :locate_answers, [tokenized_answers, text], opts)
  end

  @doc """
  Python module attribute `dspy.dsp.utils.main_thread_config`.

  ## Returns

  - `Dspy.Dsp.Utils.Utils.Dotdict.t()`
  """
  @spec main_thread_config() ::
          {:ok, Dspy.Dsp.Utils.Utils.Dotdict.t()} | {:error, Snakepit.Error.t()}
  def main_thread_config() do
    SnakeBridge.Runtime.get_module_attr(__MODULE__, :main_thread_config)
  end

  @doc """
  Python binding for `dspy.dsp.utils.print_message`.

  ## Parameters

  - `s` (term())
  - `condition` (term() keyword-only default: True)
  - `pad` (term() keyword-only default: False)
  - `sep` (term() keyword-only default: None)

  ## Returns

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

  @doc """
  Requires items in list to already be grouped by first item.

  ## Parameters

  - `lst` (term())

  ## Returns

  - `term()`
  """
  @spec process_grouped_by_first_item(term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def process_grouped_by_first_item(lst, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :process_grouped_by_first_item, [lst], opts)
  end

  @doc """
  Python module attribute `dspy.dsp.utils.STokenizer`.

  ## Returns

  - `Dspy.Dsp.Utils.Dpr.SimpleTokenizer.t()`
  """
  @spec s_tokenizer() ::
          {:ok, Dspy.Dsp.Utils.Dpr.SimpleTokenizer.t()} | {:error, Snakepit.Error.t()}
  def s_tokenizer() do
    SnakeBridge.Runtime.get_module_attr(__MODULE__, "STokenizer")
  end

  @doc """
  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.

  ## Returns

  - `Dspy.Dsp.Utils.SettingsClass3.t()`
  """
  @spec settings() :: {:ok, Dspy.Dsp.Utils.SettingsClass3.t()} | {:error, Snakepit.Error.t()}
  def settings() do
    SnakeBridge.Runtime.get_module_attr(__MODULE__, :settings)
  end

  @doc """
  Strips accents from a piece of text.

  ## Parameters

  - `text` (term())

  ## Returns

  - `term()`
  """
  @spec strip_accents(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def strip_accents(text, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :strip_accents, [text], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.timestamp`.

  ## Parameters

  - `daydir` (term() default: False)

  ## Returns

  - `term()`
  """
  @spec timestamp() :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec timestamp(keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec timestamp(term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec timestamp(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def timestamp() do
    SnakeBridge.Runtime.call(__MODULE__, :timestamp, [], [])
  end

  def timestamp(opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :timestamp, [], opts)
  end

  def timestamp(daydir) do
    SnakeBridge.Runtime.call(__MODULE__, :timestamp, [daydir], [])
  end

  def timestamp(daydir, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :timestamp, [daydir], opts)
  end

  @doc """
  Python binding for `dspy.dsp.utils.zip_first`.

  ## Parameters

  - `list1` (term())
  - `list2` (term())

  ## Returns

  - `term()`
  """
  @spec zip_first(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def zip_first(list1, list2, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :zip_first, [list1, list2], opts)
  end

  @doc """
  A much faster A, B, C = zip(*[(a, b, c), (a, b, c), ...])

  May return lists or tuples.

  ## Parameters

  - `data_list` (term())
  - `lazy` (term() default: False)

  ## Returns

  - `term()`
  """
  @spec zipstar(term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec zipstar(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec zipstar(term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec zipstar(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def zipstar(data_list) do
    SnakeBridge.Runtime.call(__MODULE__, :zipstar, [data_list], [])
  end

  def zipstar(data_list, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :zipstar, [data_list], opts)
  end

  def zipstar(data_list, lazy) do
    SnakeBridge.Runtime.call(__MODULE__, :zipstar, [data_list, lazy], [])
  end

  def zipstar(data_list, lazy, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :zipstar, [data_list, lazy], opts)
  end
end