open_responses

defmodule OpenResponses.Tool do
  @moduledoc """
  Behaviour for hosted (server-side) tool implementations.

  Hosted tools execute inside the agentic loop without any client involvement.
  When the model calls a tool whose name is registered in `config :open_responses, :hosted_tools`,
  the loop dispatches it here, collects the result, and continues sampling — all
  transparently.

  ## Implementing a tool

  ```elixir
  defmodule MyApp.Tools.TimeZone do
    @behaviour OpenResponses.Tool

    @impl OpenResponses.Tool
    def execute(%{"timezone" => tz}, _context) do
      case DateTime.now(tz) do
        {:ok, dt} -> {:ok, Calendar.strftime(dt, "%Y-%m-%d %H:%M:%S %Z")}
        {:error, _} -> {:error, "Unknown timezone: \#{tz}"}
      end
    end
  end
  ```

  ## Registering a tool

  ```elixir
  config :open_responses, :hosted_tools, %{
    "get_time" => MyApp.Tools.TimeZone
  }
  ```

  The key is the tool name the model uses. See the [Tool Dispatch guide](tool_dispatch.html).
  """

  @callback execute(arguments :: map(), context :: map()) ::
              {:ok, String.t()} | {:error, term()}
end