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

  @doc "Extract content from a single bytes or URI input."
  @spec extract(keyword()) :: {:ok, map()} | {:error, atom, String.t()}
  def extract(opts \\ []) do
    Xberg.Native.extract_async(
  case Keyword.get(opts, :input) do nil -> nil; v when is_binary(v) -> v; v -> Jason.encode!(v) end,
  case Keyword.get(opts, :config) do nil -> nil; v when is_binary(v) -> v; v -> Jason.encode!(v) end
    )
  end

  @doc "Extract content from multiple bytes or URI inputs."
  @spec extract_batch(keyword()) :: {:ok, map()} | {:error, atom, String.t()}
  def extract_batch(opts \\ []) do
    Xberg.Native.extract_batch_async(
  case Keyword.get(opts, :inputs) do nil -> nil; v when is_binary(v) -> v; v -> Jason.encode!(v) end,
  case Keyword.get(opts, :config) do nil -> nil; v when is_binary(v) -> v; v -> Jason.encode!(v) end
    )
  end

  @doc "Discover all pages and sitemaps reachable from `uri` without extracting document content."
  @spec map_url(String.t()) :: {:ok, map()} | {:error, atom, String.t()}
  def map_url(uri) do
    Xberg.Native.map_url_async(uri, nil)
  end

  @doc "Discover all pages and sitemaps reachable from `uri` without extracting document content."
  @spec map_url(String.t(), String.t() | nil) :: {:ok, map()} | {:error, atom, String.t()}
  def map_url(uri, config) do
  Xberg.Native.map_url_async(uri, (cond do is_nil(config) -> nil; is_binary(config) -> config; true -> Jason.encode!(config) end))
  end

  @doc "List all supported document formats."
  @spec list_supported_formats() :: [map()]
  def list_supported_formats do
    Xberg.Native.list_supported_formats()
  end

  @doc "Clear all embedding backends from the global registry."
  @spec clear_embedding_backends() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_embedding_backends do
    Xberg.Native.clear_embedding_backends()
  end

  @doc "List the names of all registered embedding backends."
  @spec list_embedding_backends() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_embedding_backends do
    Xberg.Native.list_embedding_backends()
  end

  @doc "List names of all registered document extractors."
  @spec list_document_extractors() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_document_extractors do
    Xberg.Native.list_document_extractors()
  end

  @doc "Clear all document extractors from the global registry."
  @spec clear_document_extractors() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_document_extractors do
    Xberg.Native.clear_document_extractors()
  end

  @doc "List all registered OCR backends."
  @spec list_ocr_backends() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_ocr_backends do
    Xberg.Native.list_ocr_backends()
  end

  @doc "Clear all OCR backends from the global registry."
  @spec clear_ocr_backends() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_ocr_backends do
    Xberg.Native.clear_ocr_backends()
  end

  @doc "List all registered post-processor names."
  @spec list_post_processors() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_post_processors do
    Xberg.Native.list_post_processors()
  end

  @doc "Remove all registered post-processors."
  @spec clear_post_processors() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_post_processors do
    Xberg.Native.clear_post_processors()
  end

  @doc "List names of all registered renderers."
  @spec list_renderers() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_renderers do
    Xberg.Native.list_renderers()
  end

  @doc "Clear all renderers from the global registry."
  @spec clear_renderers() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_renderers do
    Xberg.Native.clear_renderers()
  end

  @doc "Clear all reranker backends from the global registry."
  @spec clear_reranker_backends() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_reranker_backends do
    Xberg.Native.clear_reranker_backends()
  end

  @doc "List the names of all registered reranker backends."
  @spec list_reranker_backends() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_reranker_backends do
    Xberg.Native.list_reranker_backends()
  end

  @doc "Clear all tokenizer backends from the global registry."
  @spec clear_tokenizer_backends() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_tokenizer_backends do
    Xberg.Native.clear_tokenizer_backends()
  end

  @doc "List the names of all registered tokenizer backends."
  @spec list_tokenizer_backends() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_tokenizer_backends do
    Xberg.Native.list_tokenizer_backends()
  end

  @doc "List names of all registered validators."
  @spec list_validators() :: {:ok, [String.t()]} | {:error, atom, String.t()}
  def list_validators do
    Xberg.Native.list_validators()
  end

  @doc "Remove all registered validators."
  @spec clear_validators() :: {:ok, nil} | {:error, atom, String.t()}
  def clear_validators do
    Xberg.Native.clear_validators()
  end

  @doc "Run chunk classification against an extraction result."
  @spec classify_chunks(String.t() | nil, map()) :: {:ok, nil} | {:error, atom, String.t()}
  def classify_chunks(result \\ nil, config) do
  Xberg.Native.classify_chunks_async((cond do is_nil(result) -> nil; is_binary(result) -> result; true -> Jason.encode!(result) end), config)
  end

  @doc "Find unmarked claims in markdown text."
  @spec find_unmarked_claims(String.t()) :: [String.t()]
  def find_unmarked_claims(markdown) do
    Xberg.Native.find_unmarked_claims(markdown)
  end

  @doc "Verify that an excerpt appears verbatim in source text."
  @spec verify_excerpt(String.t(), String.t()) :: boolean()
  def verify_excerpt(excerpt, source_text) do
    Xberg.Native.verify_excerpt(excerpt, source_text)
  end

  @doc "Score a query against a document using ColBERT's MaxSim operator: for each query token vector, take the maximum dot product against any document token vector, then sum across query tokens."
  @spec max_sim_score(map(), map()) :: float()
  def max_sim_score(query, doc) do
    Xberg.Native.max_sim_score(query, doc)
  end

  @doc "Rank a set of documents against a query by MaxSim score, descending."
  @spec max_sim_rank(map(), [map()]) :: [map()]
  def max_sim_rank(query, docs) do
  Xberg.Native.max_sim_rank(query, (cond do is_nil(docs) -> nil; is_binary(docs) -> docs; true -> Jason.encode!(docs) end))
  end

  @doc "Create a fresh counter with no previous state."
  def tokencounter_new do
    Xberg.Native.tokencounter_new()
  end

  @doc "Compile the given JSON text as a Draft 2020-12 meta-schema."
  def metaschema_compile(meta_schema_json) do
    Xberg.Native.metaschema_compile(meta_schema_json)
  end

  @doc "Validate `raw` against the meta-schema and deserialize into a [`Preset`],"
  def metaschema_parse_preset(obj, path, raw) do
    Xberg.Native.metaschema_parse_preset(obj, path, raw)
  end

  @doc "Build the registry from preset files embedded at compile time under"
  def registry_load_embedded do
    Xberg.Native.registry_load_embedded()
  end

  @doc "Return the global registry, loading it on first access."
  def registry_global do
    Xberg.Native.registry_global()
  end

  @doc "Look up a preset by its identifier."
  def registry_get(obj, id) do
    Xberg.Native.registry_get(obj, id)
  end

  @doc "Materialize a [`PresetSummary`] list for the public registry endpoint."
  def registry_summaries(obj) do
    Xberg.Native.registry_summaries(obj)
  end

  @doc "Number of presets currently loaded."
  def registry_len(obj) do
    Xberg.Native.registry_len(obj)
  end

  @doc "Whether the registry contains zero presets."
  def registry_is_empty(obj) do
    Xberg.Native.registry_is_empty(obj)
  end

  @doc "Read raw sample bytes for `<preset_id>` from"
  def registry_sample_bytes(obj, preset_id, name) do
    Xberg.Native.registry_sample_bytes(obj, preset_id, name)
  end

  @doc "Load additional preset files from a runtime directory and insert them"
  def registry_extend_from_dir(obj, dir) do
    Xberg.Native.registry_extend_from_dir(obj, dir)
  end

  defmodule OcrBackend.Host do
    @moduledoc """
    Typed host interface for the `OcrBackend` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_ocr_backend`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `process_image` trait call."
    @callback process_image(binary(), map()) :: {:ok, map()} | {:error, atom, String.t()}

    @doc "Handle the `process_image_file` trait call."
    @callback process_image_file(String.t(), map()) :: {:ok, map()} | {:error, atom, String.t()}

    @doc "Handle the `supports_language` trait call."
    @callback supports_language(String.t()) :: boolean()

    @doc "Handle the `backend_type` trait call."
    @callback backend_type() :: map()

    @doc "Handle the `supported_languages` trait call."
    @callback supported_languages() :: [String.t()]

    @doc "Handle the `supports_table_detection` trait call."
    @callback supports_table_detection() :: boolean()

    @doc "Handle the `supports_document_processing` trait call."
    @callback supports_document_processing() :: boolean()

    @doc "Handle the `emits_structured_markdown` trait call."
    @callback emits_structured_markdown() :: boolean()

    @doc "Handle the `process_document` trait call."
    @callback process_document(String.t(), map()) :: {:ok, map()} | {:error, atom, String.t()}

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [process_image_file: 2, supported_languages: 0, supports_table_detection: 0, supports_document_processing: 0, emits_structured_markdown: 0, process_document: 2, initialize: 0, shutdown: 0]
  end

  @doc """
  Register a OcrBackend plugin with a GenServer PID and name.

  The GenServer should dispatch `{:trait_call, ...}` messages to a module that
  implements the `OcrBackend.Host` behaviour.

  The optional `implemented_methods` lists the function names the implementation
  module exports; Rust-defaulted trait methods outside this list keep their Rust
  default behavior. The scaffolded bridge module's `register/1` fills it in
  automatically from the implementation module's exports.
  """
  @spec register_ocr_backend(pid(), String.t(), [String.t()]) :: :ok | :error
  def register_ocr_backend(genserver_pid, plugin_name, implemented_methods \\ []) do
    Xberg.Native.register_ocr_backend(genserver_pid, plugin_name, implemented_methods)
  end
  @doc "Unregister a previously registered OcrBackend plugin by name."
  @spec unregister_ocr_backend(String.t() | keyword(String.t())) :: :ok | :error
  def unregister_ocr_backend(name_or_opts) do
    name = case name_or_opts do
      # Positional form: unregister_fn("name")
      n when is_binary(n) -> n
      # Keyword-list form from Elixir: unregister_fn([{:name, "name"}])
      # This happens when tests use `unregister_fn(name: "value")` with force_keyword_args
      opts when is_list(opts) -> Keyword.get(opts, :name, "")
      _ -> ""
    end
    Xberg.Native.unregister_ocr_backend(name)
  end
  defmodule PostProcessor.Host do
    @moduledoc """
    Typed host interface for the `PostProcessor` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_post_processor`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `process` trait call."
    @callback process(map(), map()) :: {:ok, nil} | {:error, atom, String.t()}

    @doc "Handle the `processing_stage` trait call."
    @callback processing_stage() :: map()

    @doc "Handle the `should_process` trait call."
    @callback should_process(map(), map()) :: boolean()

    @doc "Handle the `estimated_duration_ms` trait call."
    @callback estimated_duration_ms(map()) :: non_neg_integer()

    @doc "Handle the `priority` trait call."
    @callback priority() :: integer()

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [should_process: 2, estimated_duration_ms: 1, priority: 0, initialize: 0, shutdown: 0]
  end

  @doc """
  Register a PostProcessor plugin with a GenServer PID and name.

  The GenServer should dispatch `{:trait_call, ...}` messages to a module that
  implements the `PostProcessor.Host` behaviour.

  The optional `implemented_methods` lists the function names the implementation
  module exports; Rust-defaulted trait methods outside this list keep their Rust
  default behavior. The scaffolded bridge module's `register/1` fills it in
  automatically from the implementation module's exports.
  """
  @spec register_post_processor(pid(), String.t(), [String.t()]) :: :ok | :error
  def register_post_processor(genserver_pid, plugin_name, implemented_methods \\ []) do
    Xberg.Native.register_post_processor(genserver_pid, plugin_name, implemented_methods)
  end
  @doc "Unregister a previously registered PostProcessor plugin by name."
  @spec unregister_post_processor(String.t() | keyword(String.t())) :: :ok | :error
  def unregister_post_processor(name_or_opts) do
    name = case name_or_opts do
      # Positional form: unregister_fn("name")
      n when is_binary(n) -> n
      # Keyword-list form from Elixir: unregister_fn([{:name, "name"}])
      # This happens when tests use `unregister_fn(name: "value")` with force_keyword_args
      opts when is_list(opts) -> Keyword.get(opts, :name, "")
      _ -> ""
    end
    Xberg.Native.unregister_post_processor(name)
  end
  defmodule Validator.Host do
    @moduledoc """
    Typed host interface for the `Validator` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_validator`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `validate` trait call."
    @callback validate(map(), map()) :: {:ok, nil} | {:error, atom, String.t()}

    @doc "Handle the `should_validate` trait call."
    @callback should_validate(map(), map()) :: boolean()

    @doc "Handle the `priority` trait call."
    @callback priority() :: integer()

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [should_validate: 2, priority: 0, initialize: 0, shutdown: 0]
  end

  @doc """
  Register a Validator plugin with a GenServer PID and name.

  The GenServer should dispatch `{:trait_call, ...}` messages to a module that
  implements the `Validator.Host` behaviour.

  The optional `implemented_methods` lists the function names the implementation
  module exports; Rust-defaulted trait methods outside this list keep their Rust
  default behavior. The scaffolded bridge module's `register/1` fills it in
  automatically from the implementation module's exports.
  """
  @spec register_validator(pid(), String.t(), [String.t()]) :: :ok | :error
  def register_validator(genserver_pid, plugin_name, implemented_methods \\ []) do
    Xberg.Native.register_validator(genserver_pid, plugin_name, implemented_methods)
  end
  @doc "Unregister a previously registered Validator plugin by name."
  @spec unregister_validator(String.t() | keyword(String.t())) :: :ok | :error
  def unregister_validator(name_or_opts) do
    name = case name_or_opts do
      # Positional form: unregister_fn("name")
      n when is_binary(n) -> n
      # Keyword-list form from Elixir: unregister_fn([{:name, "name"}])
      # This happens when tests use `unregister_fn(name: "value")` with force_keyword_args
      opts when is_list(opts) -> Keyword.get(opts, :name, "")
      _ -> ""
    end
    Xberg.Native.unregister_validator(name)
  end
  defmodule DocumentExtractor.Host do
    @moduledoc """
    Typed host interface for the `DocumentExtractor` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_document_extractor`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `extract` trait call."
    @callback extract(map(), map()) :: {:ok, map()} | {:error, atom, String.t()}

    @doc "Handle the `supported_mime_types` trait call."
    @callback supported_mime_types() :: [String.t()]

    @doc "Handle the `priority` trait call."
    @callback priority() :: integer()

    @doc "Handle the `can_handle` trait call."
    @callback can_handle(String.t(), String.t()) :: boolean()

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [priority: 0, can_handle: 2, initialize: 0, shutdown: 0]
  end

  defmodule EmbeddingBackend.Host do
    @moduledoc """
    Typed host interface for the `EmbeddingBackend` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_embedding_backend`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `dimensions` trait call."
    @callback dimensions() :: non_neg_integer()

    @doc "Handle the `embed` trait call."
    @callback embed([String.t()]) :: {:ok, [[float()]]} | {:error, atom, String.t()}

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [initialize: 0, shutdown: 0]
  end

  @doc """
  Register a EmbeddingBackend plugin with a GenServer PID and name.

  The GenServer should dispatch `{:trait_call, ...}` messages to a module that
  implements the `EmbeddingBackend.Host` behaviour.

  The optional `implemented_methods` lists the function names the implementation
  module exports; Rust-defaulted trait methods outside this list keep their Rust
  default behavior. The scaffolded bridge module's `register/1` fills it in
  automatically from the implementation module's exports.
  """
  @spec register_embedding_backend(pid(), String.t(), [String.t()]) :: :ok | :error
  def register_embedding_backend(genserver_pid, plugin_name, implemented_methods \\ []) do
    Xberg.Native.register_embedding_backend(genserver_pid, plugin_name, implemented_methods)
  end
  @doc "Unregister a previously registered EmbeddingBackend plugin by name."
  @spec unregister_embedding_backend(String.t() | keyword(String.t())) :: :ok | :error
  def unregister_embedding_backend(name_or_opts) do
    name = case name_or_opts do
      # Positional form: unregister_fn("name")
      n when is_binary(n) -> n
      # Keyword-list form from Elixir: unregister_fn([{:name, "name"}])
      # This happens when tests use `unregister_fn(name: "value")` with force_keyword_args
      opts when is_list(opts) -> Keyword.get(opts, :name, "")
      _ -> ""
    end
    Xberg.Native.unregister_embedding_backend(name)
  end
  defmodule Renderer.Host do
    @moduledoc """
    Typed host interface for the `Renderer` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_renderer`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `render_result` trait call."
    @callback render_result(map()) :: {:ok, String.t()} | {:error, atom, String.t()}

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [render_result: 1, initialize: 0, shutdown: 0]
  end

  defmodule RerankerBackend.Host do
    @moduledoc """
    Typed host interface for the `RerankerBackend` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_reranker_backend`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `rerank` trait call."
    @callback rerank(String.t(), [String.t()]) :: {:ok, [float()]} | {:error, atom, String.t()}

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [initialize: 0, shutdown: 0]
  end

  @doc """
  Register a RerankerBackend plugin with a GenServer PID and name.

  The GenServer should dispatch `{:trait_call, ...}` messages to a module that
  implements the `RerankerBackend.Host` behaviour.

  The optional `implemented_methods` lists the function names the implementation
  module exports; Rust-defaulted trait methods outside this list keep their Rust
  default behavior. The scaffolded bridge module's `register/1` fills it in
  automatically from the implementation module's exports.
  """
  @spec register_reranker_backend(pid(), String.t(), [String.t()]) :: :ok | :error
  def register_reranker_backend(genserver_pid, plugin_name, implemented_methods \\ []) do
    Xberg.Native.register_reranker_backend(genserver_pid, plugin_name, implemented_methods)
  end
  @doc "Unregister a previously registered RerankerBackend plugin by name."
  @spec unregister_reranker_backend(String.t() | keyword(String.t())) :: :ok | :error
  def unregister_reranker_backend(name_or_opts) do
    name = case name_or_opts do
      # Positional form: unregister_fn("name")
      n when is_binary(n) -> n
      # Keyword-list form from Elixir: unregister_fn([{:name, "name"}])
      # This happens when tests use `unregister_fn(name: "value")` with force_keyword_args
      opts when is_list(opts) -> Keyword.get(opts, :name, "")
      _ -> ""
    end
    Xberg.Native.unregister_reranker_backend(name)
  end
  defmodule TokenizerBackend.Host do
    @moduledoc """
    Typed host interface for the `TokenizerBackend` plugin bridge.

    A plugin handler module implements this behaviour and is registered with
    `register_tokenizer_backend`. Each callback receives the decoded arguments for a
    trait method and returns the method's result. The dispatching GenServer
    passes the decoded `args` map to the callback for the corresponding method.

    The optional callbacks are Rust-defaulted trait methods (plus the
    `initialize`/`shutdown` lifecycle hooks): the bridge calls them when the
    module exports them, otherwise the trait's Rust default behavior applies.
    """

    @doc "Handle the `count_tokens` trait call."
    @callback count_tokens(String.t()) :: non_neg_integer()

    @doc "Optional lifecycle hook, called at plugin registration."
    @callback initialize() :: any()

    @doc "Optional lifecycle hook, called at plugin unregistration."
    @callback shutdown() :: any()

    @optional_callbacks [initialize: 0, shutdown: 0]
  end

  @doc """
  Register a TokenizerBackend plugin with a GenServer PID and name.

  The GenServer should dispatch `{:trait_call, ...}` messages to a module that
  implements the `TokenizerBackend.Host` behaviour.

  The optional `implemented_methods` lists the function names the implementation
  module exports; Rust-defaulted trait methods outside this list keep their Rust
  default behavior. The scaffolded bridge module's `register/1` fills it in
  automatically from the implementation module's exports.
  """
  @spec register_tokenizer_backend(pid(), String.t(), [String.t()]) :: :ok | :error
  def register_tokenizer_backend(genserver_pid, plugin_name, implemented_methods \\ []) do
    Xberg.Native.register_tokenizer_backend(genserver_pid, plugin_name, implemented_methods)
  end
  @doc "Unregister a previously registered TokenizerBackend plugin by name."
  @spec unregister_tokenizer_backend(String.t() | keyword(String.t())) :: :ok | :error
  def unregister_tokenizer_backend(name_or_opts) do
    name = case name_or_opts do
      # Positional form: unregister_fn("name")
      n when is_binary(n) -> n
      # Keyword-list form from Elixir: unregister_fn([{:name, "name"}])
      # This happens when tests use `unregister_fn(name: "value")` with force_keyword_args
      opts when is_list(opts) -> Keyword.get(opts, :name, "")
      _ -> ""
    end
    Xberg.Native.unregister_tokenizer_backend(name)
  end
end