liter_llm

# This file is auto-generated by alef — DO NOT EDIT.
# alef:hash:c7947a41084f71e69944233535fbeda5cd13b37144078f1895b6b57a7802d3fe
# To regenerate: alef generate
# To verify freshness: alef verify --exit-code
defmodule LiterLlm do
  @moduledoc "High-level API for liter_llm"

  @doc "Create a new LLM client with simple scalar configuration."
  @spec create_client(String.t(), keyword()) :: {:ok, reference()} | {:error, atom, String.t()}
  def create_client(api_key, opts \\ []) do
    LiterLlm.Native.create_client(
      api_key,
      Keyword.get(opts, :base_url),
      Keyword.get(opts, :timeout_secs),
      Keyword.get(opts, :max_retries),
      Keyword.get(opts, :model_hint)
    )
  end

  @doc "Create a new LLM client from a JSON string."
  @spec create_client_from_json(String.t()) :: {:ok, reference()} | {:error, atom, String.t()}
  def create_client_from_json(json) do
    LiterLlm.Native.create_client_from_json(json)
  end

  @doc "Encode bytes as a base64 data URL: `data:<mime>;base64,<b64>`."
  @spec encode_data_url(binary()) :: String.t()
  def encode_data_url(bytes) do
    LiterLlm.Native.encode_data_url(bytes, nil)
  end

  @doc "Encode bytes as a base64 data URL: `data:<mime>;base64,<b64>`."
  @spec encode_data_url(binary(), String.t() | nil) :: String.t()
  def encode_data_url(bytes, mime) do
    LiterLlm.Native.encode_data_url(bytes, mime)
  end

  @doc "Decode a base64 data URL into [`DecodedDataUrl`]."
  @spec decode_data_url(String.t()) :: map() | nil
  def decode_data_url(url) do
    LiterLlm.Native.decode_data_url(url)
  end

  @doc "Register a custom provider in the global runtime registry."
  @spec register_custom_provider(map()) :: {:ok, nil} | {:error, atom, String.t()}
  def register_custom_provider(config) do
    LiterLlm.Native.register_custom_provider(config)
  end

  @doc "Remove a previously registered custom provider by name."
  @spec unregister_custom_provider(String.t()) :: {:ok, boolean()} | {:error, atom, String.t()}
  def unregister_custom_provider(name) do
    LiterLlm.Native.unregister_custom_provider(name)
  end

  @doc "Return the capability flags for a named provider."
  @spec capabilities(String.t()) :: map()
  def capabilities(provider_name) do
    LiterLlm.Native.capabilities(provider_name)
  end

  @doc "Return all provider configs from the registry."
  @spec all_providers() :: {:ok, [map()]} | {:error, atom, String.t()}
  def all_providers do
    LiterLlm.Native.all_providers()
  end

  @doc "Return the set of complex provider names."
  @spec complex_provider_names() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def complex_provider_names do
    LiterLlm.Native.complex_provider_names()
  end

  @doc "Calculate the estimated cost of a completion given a model name and token counts."
  @spec completion_cost(String.t(), non_neg_integer(), non_neg_integer()) :: float() | nil
  def completion_cost(model, prompt_tokens, completion_tokens) do
    LiterLlm.Native.completion_cost(model, prompt_tokens, completion_tokens)
  end

  @doc "Calculate the estimated cost of a completion, accounting for cached (cache-hit) prompt tokens billed at the provider's discounted rate."
  @spec completion_cost_with_cache(
          String.t(),
          non_neg_integer(),
          non_neg_integer(),
          non_neg_integer()
        ) :: float() | nil
  def completion_cost_with_cache(model, prompt_tokens, cached_tokens, completion_tokens) do
    LiterLlm.Native.completion_cost_with_cache(model, prompt_tokens, cached_tokens, completion_tokens)
  end

  @doc "Look up FFI-friendly pricing and capability metadata for a model."
  @spec model_info(String.t()) :: map() | nil
  def model_info(model) do
    LiterLlm.Native.model_info(model)
  end

  @doc "Remove all guardrails from the global registry."
  @spec clear() :: nil
  def clear do
    LiterLlm.Native.clear()
  end

  @doc "Count tokens in a text string using the tokenizer for the given model."
  @spec count_tokens(String.t(), String.t()) ::
          {:ok, non_neg_integer()} | {:error, atom, String.t()}
  def count_tokens(model, text) do
    LiterLlm.Native.count_tokens(model, text)
  end

  @doc "Count tokens for a full [`ChatCompletionRequest`]."
  @spec count_request_tokens(String.t()) :: {:ok, non_neg_integer()} | {:error, atom, String.t()}
  def count_request_tokens(model) do
    LiterLlm.Native.count_request_tokens(model, nil)
  end

  @doc "Count tokens for a full [`ChatCompletionRequest`]."
  @spec count_request_tokens(String.t(), String.t() | nil) ::
          {:ok, non_neg_integer()} | {:error, atom, String.t()}
  def count_request_tokens(model, req) do
    LiterLlm.Native.count_request_tokens(model, (cond do is_nil(req) -> nil; is_binary(req) -> req; true -> Jason.encode!(req) end))
  end

  @doc "Assert that `current_len + incoming` does not exceed `limit`."
  @spec check_bound(String.t(), non_neg_integer(), non_neg_integer(), non_neg_integer()) ::
          {:ok, nil} | {:error, atom, String.t()}
  def check_bound(context, current_len, incoming, limit) do
    LiterLlm.Native.check_bound(context, current_len, incoming, limit)
  end

  @doc "Install the `ring` crypto provider as the rustls process default, idempotently."
  @spec ensure_crypto_provider() :: nil
  def ensure_crypto_provider do
    LiterLlm.Native.ensure_crypto_provider()
  end

  @doc "Install the overlay registry from a raw catalog JSON string, bypassing the network and disk cache entirely."
  @spec install_catalog_overlay_from_str(String.t()) :: {:ok, nil} | {:error, atom, String.t()}
  def install_catalog_overlay_from_str(catalog_json) do
    LiterLlm.Native.install_catalog_overlay_from_str(catalog_json)
  end

  @doc "Clear the overlay registry, reverting `completion_cost`, `completion_cost_with_cache`, and `model_info` to the embedded catalog."
  @spec clear_catalog_overlay() :: nil
  def clear_catalog_overlay do
    LiterLlm.Native.clear_catalog_overlay()
  end

  @doc "Refresh the runtime catalog overlay per `config`."
  @spec refresh_catalog() :: {:ok, map()} | {:error, atom, String.t()}
  def refresh_catalog do
    LiterLlm.Native.refresh_catalog_async(nil)
  end

  @doc "Refresh the runtime catalog overlay per `config`."
  @spec refresh_catalog(String.t() | nil) :: {:ok, map()} | {:error, atom, String.t()}
  def refresh_catalog(config) do
    LiterLlm.Native.refresh_catalog_async((cond do is_nil(config) -> nil; is_binary(config) -> config; true -> Jason.encode!(config) end))
  end

  @doc "Returns the canonical HTTP status code associated with this error."
  @spec literllmerror_status_code(String.t()) :: non_neg_integer()
  def literllmerror_status_code(msg) do
    LiterLlm.Native.literllmerror_status_code(msg)
  end

  @doc "Returns `true` for errors that are worth retrying on a different service or deployment (transient failures)."
  @spec literllmerror_is_transient(String.t()) :: boolean()
  def literllmerror_is_transient(msg) do
    LiterLlm.Native.literllmerror_is_transient(msg)
  end

  @doc "Return the OpenTelemetry `error.type` string for this error variant."
  @spec literllmerror_error_type(String.t()) :: String.t()
  def literllmerror_error_type(msg) do
    LiterLlm.Native.literllmerror_error_type(msg)
  end

  @doc false
  def defaultclient_chat_stream_start(client, req) do
    LiterLlm.Native.defaultclient_chat_stream_start(client, req)
  end

  @doc false
  def defaultclient_chat_stream_next(handle) do
    LiterLlm.Native.defaultclient_chat_stream_next(handle)
  end

  @doc "Streaming `chat_stream` — returns an `Enumerable` of decoded chunk maps."
  def chat_stream(client, req) do
    req_json =
      case req do
        nil -> nil
        s when is_binary(s) -> s
        other -> Jason.encode!(other)
      end

    case LiterLlm.Native.defaultclient_chat_stream_start(client, req_json) do
      {:ok, handle} ->
        stream =
          Stream.unfold(handle, fn h ->
            case LiterLlm.Native.defaultclient_chat_stream_next(h) do
              {:ok, nil} ->
                nil

              {:ok, chunk_json} ->
                {Jason.decode!(chunk_json, keys: :atoms), h}

              {:error, reason} ->
                raise LiterLlm.StreamError,
                  message: "chat_stream stream failed: #{inspect(reason)}",
                  reason: reason,
                  adapter: :chat_stream
            end
          end)

        {:ok, stream}

      {:error, reason} ->
        {:error, reason}
    end
  end

  def defaultclient_chat_async(obj, req) do
    LiterLlm.Native.defaultclient_chat_async(obj, req)
  end

  def defaultclient_embed_async(obj, req) do
    LiterLlm.Native.defaultclient_embed_async(obj, req)
  end

  def defaultclient_list_models_async(obj) do
    LiterLlm.Native.defaultclient_list_models_async(obj)
  end

  def defaultclient_image_generate_async(obj, req) do
    LiterLlm.Native.defaultclient_image_generate_async(obj, req)
  end

  def defaultclient_speech_async(obj, req) do
    LiterLlm.Native.defaultclient_speech_async(obj, req)
  end

  def defaultclient_transcribe_async(obj, req) do
    LiterLlm.Native.defaultclient_transcribe_async(obj, req)
  end

  def defaultclient_moderate_async(obj, req) do
    LiterLlm.Native.defaultclient_moderate_async(obj, req)
  end

  def defaultclient_rerank_async(obj, req) do
    LiterLlm.Native.defaultclient_rerank_async(obj, req)
  end

  def defaultclient_search_async(obj, req) do
    LiterLlm.Native.defaultclient_search_async(obj, req)
  end

  def defaultclient_ocr_async(obj, req) do
    LiterLlm.Native.defaultclient_ocr_async(obj, req)
  end

  def defaultclient_create_file_async(obj, req) do
    LiterLlm.Native.defaultclient_create_file_async(obj, req)
  end

  def defaultclient_retrieve_file_async(obj, file_id) do
    LiterLlm.Native.defaultclient_retrieve_file_async(obj, file_id)
  end

  def defaultclient_delete_file_async(obj, file_id) do
    LiterLlm.Native.defaultclient_delete_file_async(obj, file_id)
  end

  def defaultclient_list_files_async(obj, query) do
    LiterLlm.Native.defaultclient_list_files_async(obj, query)
  end

  def defaultclient_file_content_async(obj, file_id) do
    LiterLlm.Native.defaultclient_file_content_async(obj, file_id)
  end

  def defaultclient_create_batch_async(obj, req) do
    LiterLlm.Native.defaultclient_create_batch_async(obj, req)
  end

  def defaultclient_retrieve_batch_async(obj, batch_id) do
    LiterLlm.Native.defaultclient_retrieve_batch_async(obj, batch_id)
  end

  def defaultclient_list_batches_async(obj, query) do
    LiterLlm.Native.defaultclient_list_batches_async(obj, query)
  end

  def defaultclient_cancel_batch_async(obj, batch_id) do
    LiterLlm.Native.defaultclient_cancel_batch_async(obj, batch_id)
  end

  def defaultclient_fetch_batch_for_polling_async(obj, batch_id) do
    LiterLlm.Native.defaultclient_fetch_batch_for_polling_async(obj, batch_id)
  end

  @doc "Poll a batch until it reaches a terminal status (Completed, Failed, Expired, Cancelled)."
  def defaultclient_wait_for_batch_async(obj, batch_id, config) do
    LiterLlm.Native.defaultclient_wait_for_batch_async(obj, batch_id, config)
  end

  def defaultclient_create_response_async(obj, req) do
    LiterLlm.Native.defaultclient_create_response_async(obj, req)
  end

  def defaultclient_retrieve_response_async(obj, response_id) do
    LiterLlm.Native.defaultclient_retrieve_response_async(obj, response_id)
  end

  def defaultclient_cancel_response_async(obj, response_id) do
    LiterLlm.Native.defaultclient_cancel_response_async(obj, response_id)
  end
end

defmodule LiterLlm.StreamError do
  @moduledoc false

  defexception [:message, :reason, :adapter]

  @impl true
  def message(%__MODULE__{message: msg}), do: msg
end