Gemini.APIs.Operations (GeminiEx v0.8.2)

View Source

Operations API for managing long-running operations.

Long-running operations are returned by asynchronous API calls that may take significant time to complete, such as:

  • Video generation
  • File imports
  • Model tuning
  • Large batch processing

Polling Pattern

The typical pattern for handling long-running operations:

# Start a long-running operation
{:ok, operation} = some_async_api_call()

# Wait for completion with polling
{:ok, completed} = Gemini.APIs.Operations.wait(operation.name,
  poll_interval: 5000,      # Check every 5 seconds
  timeout: 600_000,         # Wait up to 10 minutes
  on_progress: fn op ->
    if progress = Gemini.Types.Operation.get_progress(op) do
      IO.puts("Progress: #{progress}%")
    end
  end
)

# Handle result
if Gemini.Types.Operation.succeeded?(completed) do
  result = completed.response
  # Process successful result
else
  error = completed.error
  # Handle error
end

Manual Polling

For more control, you can poll manually:

{:ok, op} = Gemini.APIs.Operations.get(operation_name)

cond do
  Operation.succeeded?(op) -> handle_success(op.response)
  Operation.failed?(op) -> handle_failure(op.error)
  Operation.running?(op) -> poll_again_later()
end

Cancellation

Some operations can be cancelled while in progress:

:ok = Gemini.APIs.Operations.cancel(operation_name)

Summary

Types

list_opts()
operation_opts()
wait_opts()

Functions

cancel(name, opts \\ [])

Cancel a running operation.

delete(name, opts \\ [])

Delete an operation.

get(name, opts \\ [])

Get the current status of an operation.

list(opts \\ [])

List operations, optionally filtered.

list_all(opts \\ [])

List all operations across all pages.

wait(name, opts \\ [])

Wait for an operation to complete.

wait_with_backoff(name, opts \\ [])

Wait for an operation with exponential backoff.

Types

list_opts()

@type list_opts() :: [
  page_size: pos_integer(),
  page_token: String.t(),
  filter: String.t(),
  auth: :gemini | :vertex_ai
]

operation_opts()

@type operation_opts() :: [{:auth, :gemini | :vertex_ai}]

wait_opts()

@type wait_opts() :: [
  poll_interval: pos_integer(),
  timeout: pos_integer(),
  on_progress: (Gemini.Types.Operation.t() -> any()),
  auth: :gemini | :vertex_ai
]

Functions

cancel(name, opts \\ [])

@spec cancel(String.t(), operation_opts()) :: :ok | {:error, term()}

Cancel a running operation.

Not all operations support cancellation. If the operation doesn't support cancellation or is already complete, this may return an error.

Parameters

  • name - Operation name
  • opts - Options

Examples

:ok = Gemini.APIs.Operations.cancel("operations/abc123")

delete(name, opts \\ [])

@spec delete(String.t(), operation_opts()) :: :ok | {:error, term()}

Delete an operation.

Typically used to clean up completed operations.

Parameters

  • name - Operation name
  • opts - Options

Examples

:ok = Gemini.APIs.Operations.delete("operations/abc123")

get(name, opts \\ [])

@spec get(String.t(), operation_opts()) ::
  {:ok, Gemini.Types.Operation.t()} | {:error, term()}

Get the current status of an operation.

Parameters

  • name - Operation name (e.g., "operations/abc123")
  • opts - Options

Examples

{:ok, op} = Gemini.APIs.Operations.get("operations/abc123")

if op.done do
  IO.puts("Operation completed")
else
  IO.puts("Still running...")
end

list(opts \\ [])

@spec list(list_opts()) ::
  {:ok, Gemini.Types.ListOperationsResponse.t()} | {:error, term()}

List operations, optionally filtered.

Parameters

  • opts - List options

Options

  • :page_size - Number of operations per page (default: 100)
  • :page_token - Token from previous response for pagination
  • :filter - Filter string (e.g., "done=true")
  • :auth - Authentication strategy

Examples

# List all operations
{:ok, response} = Gemini.APIs.Operations.list()

# List only completed operations
{:ok, response} = Gemini.APIs.Operations.list(filter: "done=true")

# With pagination
{:ok, response} = Gemini.APIs.Operations.list(page_size: 10)

list_all(opts \\ [])

@spec list_all(list_opts()) :: {:ok, [Gemini.Types.Operation.t()]} | {:error, term()}

List all operations across all pages.

Automatically handles pagination to retrieve all operations.

Parameters

  • opts - List options

Examples

{:ok, all_ops} = Gemini.APIs.Operations.list_all()
completed = Enum.filter(all_ops, &Operation.complete?/1)

wait(name, opts \\ [])

@spec wait(String.t(), wait_opts()) ::
  {:ok, Gemini.Types.Operation.t()} | {:error, term()}

Wait for an operation to complete.

Polls the operation status until it reaches a terminal state (done = true), or the timeout is reached.

Parameters

  • name - Operation name
  • opts - Wait options

Options

  • :poll_interval - Milliseconds between status checks (default: 5000)
  • :timeout - Maximum wait time in milliseconds (default: 600000 = 10 min)
  • :on_progress - Callback for status updates fn(Operation.t()) -> any()

Returns

  • {:ok, Operation.t()} - Completed operation (check done, error, response)
  • {:error, :timeout} - Timed out waiting for completion
  • {:error, reason} - Failed to poll status

Examples

# Simple wait
{:ok, completed} = Gemini.APIs.Operations.wait("operations/abc123")

# With progress tracking
{:ok, completed} = Gemini.APIs.Operations.wait("operations/abc123",
  poll_interval: 2000,
  timeout: 300_000,
  on_progress: fn op ->
    if progress = Operation.get_progress(op) do
      IO.puts("Progress: #{progress}%")
    end
  end
)

# Handle result
cond do
  Operation.succeeded?(completed) ->
    IO.puts("Success: #{inspect(completed.response)}")
  Operation.failed?(completed) ->
    IO.puts("Failed: #{completed.error.message}")
end

wait_with_backoff(name, opts \\ [])

@spec wait_with_backoff(
  String.t(),
  keyword()
) :: {:ok, Gemini.Types.Operation.t()} | {:error, term()}

Wait for an operation with exponential backoff.

Similar to wait/2 but uses exponential backoff for polling intervals, which is more efficient for operations that may take a long time.

Parameters

  • name - Operation name
  • opts - Wait options

Options

Same as wait/2 plus:

  • :initial_delay - Initial delay in milliseconds (default: 1000)
  • :max_delay - Maximum delay in milliseconds (default: 30000)
  • :multiplier - Backoff multiplier (default: 2)

Examples

{:ok, completed} = Gemini.APIs.Operations.wait_with_backoff("operations/abc123",
  initial_delay: 1000,
  max_delay: 30_000,
  timeout: 600_000
)