# `Nous.Research.Coordinator`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/research/coordinator.ex#L1)

The main research loop coordinator.

Orchestrates: plan -> search -> synthesize -> evaluate gaps -> re-plan if needed.
Broadcasts progress via callbacks/PubSub. Supports HITL checkpoints.

# `state`

```elixir
@type state() :: %{
  query: String.t(),
  iteration: non_neg_integer(),
  max_iterations: non_neg_integer(),
  all_findings: [Nous.Research.Finding.t()],
  synthesis: map() | nil,
  opts: keyword(),
  start_time: integer(),
  total_tokens: non_neg_integer()
}
```

# `run`

```elixir
@spec run(
  String.t(),
  keyword()
) :: {:ok, Nous.Research.Report.t()} | {:error, term()}
```

Run the full research loop.

## Options

- `:model` - Model for coordination/synthesis (default: "openai:gpt-4o-mini")
- `:search_tool` - Search function or list of tools (required)
- `:max_iterations` - Max research iterations (default: 5)
- `:timeout` - Hard timeout in ms (default: 10 minutes)
- `:strategy` - Planning strategy :parallel | :sequential | :tree (default: :parallel)
- `:on_plan_ready` - Callback when plan is generated: fn plan -> :approve | {:edit, plan} | :reject end
- `:on_iteration_complete` - Callback after each iteration: fn synthesis -> :continue | :stop end
- `:callbacks` - Map of callback functions for progress events
- `:notify_pid` - PID to receive progress messages
- `:deps` - Dependencies to pass to search tools

---

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