dspex

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

defmodule Dspy.CodeInterpreter do
  @moduledoc """
  Protocol for code execution environments (interpreters).

  Implementations must provide:
  - start(): Initialize the interpreter (optional, can be lazy)
  - execute(): Run code and return results
  - shutdown(): Clean up resources

  The interpreter maintains state across execute() calls within a session,
  allowing variables defined in one call to be used in subsequent calls.

  Lifecycle:
      1. Create instance (config only, no resources allocated)
      2. start() - Initialize interpreter (explicit) or let execute() do it (lazy)
      3. execute() - Run code (can be called many times)
      4. shutdown() - Release resources

  Example implementations:
      - LocalInterpreter: Deno/Pyodide WASM interpreter (local)
      - MockInterpreter: Scriptable responses for testing

  Pooling:
      For interpreter pooling, call start() to pre-warm instances, then
      distribute execute() calls across the pool.
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "CodeInterpreter"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Constructs `CodeInterpreter`.

  ## 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 """
  Execute Python code and return the result.



  ## Parameters

  - `code` - Python code to execute
  - `variables` - Variables to inject into the namespace before execution. These are available as top-level variables in the code.

  ## Raises

  - `CodeInterpreterError` - On runtime errors (undefined vars, tool failures, etc.)
  - `SyntaxError` - On invalid Python syntax

  ## Notes

  State persists across calls. Variables defined in one execute()
      call are available in subsequent calls until shutdown().

      If start() was not called, implementations should call it lazily.

  ## Returns

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

  @doc """
  Release resources and terminate the interpreter session.

  After shutdown(), the interpreter should not be used again.
  A new instance should be created for a fresh session.

  ## Returns

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

  @doc """
  Initialize the interpreter and allocate resources.

  This method prepares the interpreter for code execution. It can be called
  explicitly to pre-warm the interpreter, or implementations may call it
  lazily on first execute().

  For pooling scenarios, call start() on multiple instances to have
  them ready before distributing work.

  Calling start() multiple times should be safe (idempotent).

  ## Returns

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

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

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

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

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