gemini_ex

defmodule Gemini.Tools do
  @moduledoc """
  High-level facade for tool registration and execution in the Gemini client.



  This module provides a convenient interface for developers to register tool

  implementations and execute function calls returned by the Gemini API. It

  integrates with the ALTAR LATER runtime for robust tool execution.



  ## Usage



      # Register a tool

      {:ok, declaration} = Altar.ADM.new_function_declaration(%{

        name: "get_weather",

        description: "Gets weather for a location",

        parameters: %{}

      })



      :ok = Gemini.Tools.register(declaration, &MyApp.Tools.get_weather/1)



      # Execute function calls from API response

      function_calls = [%Altar.ADM.FunctionCall{...}]

      {:ok, results} = Gemini.Tools.execute_calls(function_calls)

  """

  alias Altar.ADM.{FunctionCall, FunctionDeclaration, ToolResult}
  alias Altar.LATER.{Registry, Executor}

  @registry_name Gemini.Tools.Registry

  @doc """
  Register a tool implementation with the LATER registry.



  - `declaration` is a validated `%Altar.ADM.FunctionDeclaration{}`

  - `fun` is an arity-1 function that accepts a map of arguments



  Returns `:ok` on success or `{:error, reason}` if registration fails.

  """
  @spec register(FunctionDeclaration.t(), (map() -> any())) :: :ok | {:error, term()}
  def register(%FunctionDeclaration{} = declaration, fun) when is_function(fun, 1) do
    Registry.register_tool(@registry_name, declaration, fun)
  end

  @doc """
  Execute a list of function calls in parallel using the LATER executor.



  Takes a list of `%Altar.ADM.FunctionCall{}` structs (typically from a

  GenerateContentResponse) and executes them concurrently, returning a list

  of `%Altar.ADM.ToolResult{}` structs.



  Returns `{:ok, [ToolResult.t()]}` on success. Individual tool failures

  are captured in the ToolResult's `is_error` field rather than causing

  the entire operation to fail.

  """
  @spec execute_calls([FunctionCall.t()]) :: {:ok, [ToolResult.t()]}
  def execute_calls(function_calls) when is_list(function_calls) do
    results =
      function_calls
      |> Task.async_stream(
        fn call ->
          {:ok, result} = Executor.execute_tool(@registry_name, call)
          result
        end,
        max_concurrency: System.schedulers_online(),
        timeout: 30_000
      )
      |> Enum.map(fn
        {:ok, result} -> result
        {:exit, reason} -> build_error_result("task_exit", reason)
      end)

    {:ok, results}
  end

  # Helper to build error results for task failures
  defp build_error_result(call_id, reason) do
    {:ok, result} =
      Altar.ADM.new_tool_result(%{
        call_id: call_id,
        is_error: true,
        content: %{error: "Task execution failed: #{inspect(reason)}"}
      })

    result
  end
end