# `Gemini.Streaming.ToolOrchestrator`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/streaming/tool_orchestrator.ex#L1)

GenServer responsible for managing a single, stateful, automatic tool-calling stream.

This orchestrator handles the complex multi-stage streaming process:
1. Starts the initial streaming HTTP request to the Gemini API
2. Buffers and inspects incoming chunks for function calls
3. When function calls are detected, stops the first stream and executes tools
4. Starts a second streaming request with the complete history including tool results
5. Proxies the final stream events to the original subscriber

The orchestrator maintains state throughout this process and handles errors gracefully.

# `orchestrator_state`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/streaming/tool_orchestrator.ex#L27)

```elixir
@type orchestrator_state() :: %{
  stream_id: String.t(),
  subscriber_pid: pid(),
  chat: Gemini.Chat.t(),
  auth_strategy: :gemini | :vertex_ai,
  config: keyword(),
  phase: :awaiting_model_call | :executing_tools | :awaiting_final_response,
  first_stream_pid: pid() | nil,
  second_stream_pid: pid() | nil,
  buffered_chunks: [map()],
  turn_limit: non_neg_integer(),
  error: term() | nil
}
```

# `child_spec`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/streaming/tool_orchestrator.ex#L15)

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start_link`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/streaming/tool_orchestrator.ex#L59)

```elixir
@spec start_link(String.t(), pid(), Gemini.Chat.t(), :gemini | :vertex_ai, keyword()) ::
  GenServer.on_start()
```

Start a new tool orchestrator for automatic streaming.

## Parameters
- `stream_id`: Unique identifier for this stream
- `subscriber_pid`: Process to receive final stream events
- `chat`: Initial chat state with history and options
- `auth_strategy`: Authentication strategy to use
- `config`: Additional configuration options

## Returns
- `{:ok, pid()}`: Orchestrator started successfully
- `{:error, reason}`: Failed to start orchestrator

---

*Consult [api-reference.md](api-reference.md) for complete listing*