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: TrainingJob

defmodule Dspy.TrainingJob do
  @moduledoc """
  A future representing an asynchronous model fine-tuning job.

  This class extends `concurrent.futures.Future` to represent a fine-tuning job
  that can be monitored and cancelled. Subclasses should implement the `status`
  method to provide job status information specific to their provider.

  Attributes:
      thread: The thread running the training job, if applicable.
      model: The model identifier being fine-tuned.
      train_data: The training data used for fine-tuning.
      train_data_format: The format of the training data.
      train_kwargs: Additional keyword arguments for training configuration.

  ## Examples

      ```python
      from dspy.clients.provider import TrainingJob

      job = TrainingJob(
      model="gpt-3.5-turbo",
      train_data=[{"messages": [...]}],
      train_data_format=TrainDataFormat.CHAT
      )
      # Check if job is done
      if job.done():
      result = job.result()
      ```
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "TrainingJob"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initializes the future. Should not be called by clients.

  ## Parameters

  - `thread` (term() default: None)
  - `model` (term() default: None)
  - `train_data` (term() default: None)
  - `train_data_format` (term() default: None)
  - `train_kwargs` (term() default: None)
  """
  @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 `TrainingJob._Future__get_result`.

  ## Returns

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

  @doc """
  Python method `TrainingJob._invoke_callbacks`.

  ## Returns

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

  @doc """
  Attaches a callable that will be called when the future finishes.



  ## Parameters

  - `fn` - A callable that will be called with this future as its only argument when the future completes or is cancelled. The callable will always be called by a thread in the same process in which it was added. If the future has already completed or been cancelled then the callable will be called immediately. These callables are called in the order that they were added.

  ## Returns

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

  @doc """
  Cancel the training job.

  Subclasses should override this method to cancel the job with the provider;
  then call the super's cancel method so that the future can be cancelled.

  ## Returns

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

  @doc """
  Return True if the future was cancelled.

  ## Returns

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

  @doc """
  Return True if the future was cancelled or finished executing.

  ## Returns

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

  @doc """
  Return the exception raised by the call that the future represents.



  ## Parameters

  - `timeout` - The number of seconds to wait for the exception if the future isn't done. If None, then there is no limit on the wait time.

  ## Raises

  - `CancelledError` - If the future was cancelled.
  - `TimeoutError` - If the future didn't finish executing before the given timeout.

  ## Returns

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

  @doc """
  Return the result of the call that the future represents.



  ## Parameters

  - `timeout` - The number of seconds to wait for the result if the future isn't done. If None, then there is no limit on the wait time.

  ## Raises

  - `CancelledError` - If the future was cancelled.
  - `TimeoutError` - If the future didn't finish executing before the given timeout.
  - `Exception` - If the call raised then that exception will be raised.

  ## Returns

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

  @doc """
  Return True if the future is currently executing.

  ## Returns

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

  @doc """
  Sets the result of the future as being the given exception.

  Should only be used by Executor implementations and unit tests.

  ## Parameters

  - `exception` (term())

  ## Returns

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

  @doc """
  Sets the return value of work associated with the future.

  Should only be used by Executor implementations and unit tests.

  ## Parameters

  - `result` (term())

  ## Returns

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

  @doc """
  Mark the future as running or process any cancel notifications.

  Should only be used by Executor implementations and unit tests.

  If the future has been cancelled (cancel() was called and returned
  True) then any threads waiting on the future completing (though calls
  to as_completed() or wait()) are notified and False is returned.

  If the future was not cancelled then it is put in the running state
  (future calls to running() will return True) and True is returned.

  This method should be called by Executor implementations before
  executing the work associated with this future. If this method returns
  False then the work should not be executed.

  ## Raises

  - `RuntimeError` - if this method was already called or if set_result() or set_exception() was called.

  ## Returns

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

  @doc """
  Get the current status of the training job.

  This method should be implemented by subclasses to return the current
  status of the training job in a format specific to the provider.

  ## Returns

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