@spec count_tokens(
  String.t() | Gemini.Types.Request.GenerateContentRequest.t(),
  Gemini.options()
) ::
  api_result(%{total_tokens: integer()})

Count tokens in the given input.

See Gemini.options/0 for available options.

Parameters

• input: String or GenerateContentRequest to count tokens for
• opts: Options including model and auth strategy

Options

• :model: Model to use for token counting (defaults to configured default model)
• :auth: Authentication strategy (:gemini or :vertex_ai)

Examples

{:ok, count} = Coordinator.count_tokens("Hello world")
{:ok, count} = Coordinator.count_tokens("Complex text", model: "gemini-2.5-pro", auth: :vertex_ai)

@spec extract_text(Gemini.Types.Response.GenerateContentResponse.t()) ::
  {:ok, String.t()} | {:error, term()}

Extract text content from a GenerateContentResponse.

Examples

{:ok, response} = Coordinator.generate_content("Hello")
{:ok, text} = Coordinator.extract_text(response)

@spec generate_content(
  String.t()
  | [Gemini.Types.Content.t()]
  | Gemini.Types.Request.GenerateContentRequest.t(),
  Gemini.options()
) :: api_result(Gemini.Types.Response.GenerateContentResponse.t())

Generate content using the specified model and input.

See Gemini.options/0 for available options.

Parameters

• input: String prompt or GenerateContentRequest struct
• opts: Options including model, auth strategy, and generation config

Examples

# Simple text generation
{:ok, response} = Coordinator.generate_content("What is AI?")

# With specific model and auth
{:ok, response} = Coordinator.generate_content(
  "Explain quantum computing",
  model: Gemini.Config.get_model(:flash_2_0_lite),
  auth: :vertex_ai,
  temperature: 0.7
)

# Using request struct
request = %GenerateContentRequest{...}
{:ok, response} = Coordinator.generate_content(request)

@spec get_model(String.t(), Gemini.options()) :: api_result(map())

Get information about a specific model.

See Gemini.options/0 for available options.

Parameters

• model_name: Name of the model to retrieve
• opts: Options including auth strategy

Examples

{:ok, model} = Coordinator.get_model(Gemini.Config.get_model(:flash_2_0_lite))
{:ok, model} = Coordinator.get_model("gemini-2.5-pro", auth: :vertex_ai)

@spec list_models(Gemini.options()) ::
  api_result(Gemini.Types.Response.ListModelsResponse.t())

List available models for the specified authentication strategy.

See Gemini.options/0 for available options.

Parameters

• opts: Options including auth strategy and pagination

Options

• :auth: Authentication strategy (:gemini or :vertex_ai)
• :page_size: Number of models per page
• :page_token: Pagination token for next page

Examples

# List models with default auth
{:ok, models_response} = Coordinator.list_models()

# List models with specific auth strategy
{:ok, models_response} = Coordinator.list_models(auth: :vertex_ai)

# With pagination
{:ok, models_response} = Coordinator.list_models(
  auth: :gemini,
  page_size: 50,
  page_token: "next_page_token"
)

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

Stop a streaming content generation.

@spec stream_generate_content(
  String.t() | Gemini.Types.Request.GenerateContentRequest.t(),
  Gemini.options()
) :: api_result(String.t())

Stream content generation with real-time response chunks.

See Gemini.options/0 for available options.

Parameters

• input: String prompt or GenerateContentRequest struct
• opts: Options including model, auth strategy, and generation config

Returns

• {:ok, stream_id}: Stream started successfully
• {:error, reason}: Failed to start stream

After starting the stream, subscribe to receive events:

{:ok, stream_id} = Coordinator.stream_generate_content("Tell me a story")
:ok = Coordinator.subscribe_stream(stream_id)

# Handle incoming messages
receive do
  {:stream_event, ^stream_id, event} ->
    IO.inspect(event, label: "Stream Event")
  {:stream_complete, ^stream_id} ->
    IO.puts("Stream completed")
  {:stream_error, ^stream_id, stream_error} ->
    IO.puts("Stream error: #{inspect(stream_error)}")
end

Examples

# Basic streaming
{:ok, stream_id} = Coordinator.stream_generate_content("Write a poem")

# With specific configuration
{:ok, stream_id} = Coordinator.stream_generate_content(
  "Explain machine learning",
  model: Gemini.Config.get_model(:flash_2_0_lite),
  auth: :gemini,
  temperature: 0.8,
  max_output_tokens: 1000
)

@spec stream_status(String.t()) :: {:ok, atom()} | {:error, term()}

Get the status of a streaming content generation.

@spec subscribe_stream(String.t(), pid()) :: :ok | {:error, term()}

Subscribe to a streaming content generation.

Parameters

• stream_id: ID of the stream to subscribe to
• subscriber_pid: Process to receive stream events (defaults to current process)

Examples

{:ok, stream_id} = Coordinator.stream_generate_content("Hello")
:ok = Coordinator.subscribe_stream(stream_id)

# In a different process
:ok = Coordinator.subscribe_stream(stream_id, target_pid)

@spec unsubscribe_stream(String.t(), pid()) :: :ok | {:error, term()}

Unsubscribe from a streaming content generation.