dspex

# Generated by SnakeBridge v0.13.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.1.2
# Python module: dspy.clients.cache
# Python class: Cache

defmodule Dspy.Clients.Cache.Cache do
  @moduledoc """
  DSPy Cache

  `Cache` provides 2 levels of caching (in the given order):
      1. In-memory cache - implemented with cachetools.LRUCache
      2. On-disk cache - implemented with diskcache.FanoutCache
  """
  def __snakebridge_python_name__, do: "dspy.clients.cache"
  def __snakebridge_python_class__, do: "Cache"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Args:

  enable_disk_cache: Whether to enable on-disk cache.
      enable_memory_cache: Whether to enable in-memory cache.
      disk_cache_dir: The directory where the disk cache is stored.
      disk_size_limit_bytes: The maximum size of the disk cache (in bytes).
      memory_max_entries: The maximum size of the in-memory cache (in number of items).

  ## Parameters

  - `enable_disk_cache` (boolean())
  - `enable_memory_cache` (boolean())
  - `disk_cache_dir` (String.t())
  - `disk_size_limit_bytes` (term() default: 10485760)
  - `memory_max_entries` (integer() default: 1000000)
  """
  @spec new(boolean(), boolean(), String.t(), list(term()), keyword()) ::
          {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(enable_disk_cache, enable_memory_cache, disk_cache_dir, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)

    SnakeBridge.Runtime.call_class(
      __MODULE__,
      :__init__,
      [enable_disk_cache, enable_memory_cache, disk_cache_dir] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  Obtain a unique cache key for the given request dictionary by hashing its JSON

  representation. For request fields having types that are known to be JSON-incompatible,
  convert them to a JSON-serializable format before hashing.

  ## Parameters

  - `request` (%{optional(String.t()) => term()})
  - `ignored_args_for_cache_key` (term() default: None)

  ## Returns

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

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

  ## Parameters

  - `request` (%{optional(String.t()) => term()})
  - `ignored_args_for_cache_key` (term() default: None)

  ## Returns

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

  @doc """
  Python method `Cache.load_memory_cache`.

  ## Parameters

  - `filepath` (String.t())
  - `allow_pickle` (boolean() default: False)

  ## Returns

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

  @doc """
  Python method `Cache.put`.

  ## Parameters

  - `request` (%{optional(String.t()) => term()})
  - `value` (term())
  - `ignored_args_for_cache_key` (term() default: None)
  - `enable_memory_cache` (boolean() default: True)

  ## Returns

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

  @doc """
  Python method `Cache.reset_memory_cache`.

  ## Returns

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

  @doc """
  Python method `Cache.save_memory_cache`.

  ## Parameters

  - `filepath` (String.t())

  ## Returns

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