# `Nous.Workflow.Engine`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/workflow/engine.ex#L1)

Core workflow execution engine.

A recursive function module (not a GenServer) that processes nodes
according to the compiled graph topology, threading state through
each step. Follows the same pattern as `Nous.AgentRunner`.

## Execution Model

Executes nodes in topological order, following edges. Supports:
- Sequential edges (always followed)
- Conditional edges (followed when predicate matches)
- Branch nodes (routing to one of multiple paths)
- Cycles (with max-iteration guards)

## Error Handling

Each node has an `error_strategy`:
- `:fail_fast` — halt immediately
- `{:retry, max, delay_ms}` — retry with delay
- `:skip` — record error, continue
- `{:fallback, node_id}` — route to fallback node

## Hooks

Workflow hooks intercept execution at key points:
- `:workflow_start` / `:workflow_end` — lifecycle events
- `:pre_node` — before each node (can pause/block)
- `:post_node` — after each node (can modify state)

## Pause/Resume

Workflows can be paused via:
- A `:pre_node` hook returning `{:pause, reason}`
- An external signal via `:atomics` pause_ref
- A `:human_checkpoint` node

# `execute`

```elixir
@spec execute(Nous.Workflow.Compiler.compiled(), map(), keyword()) ::
  {:ok, Nous.Workflow.State.t()}
  | {:suspended, Nous.Workflow.State.t(), map()}
  | {:error, term()}
```

Execute a compiled workflow from its entry node.

## Options

- `:max_iterations` — max cycle iterations per node (default: 10)
- `:deps` — dependencies passed to agents/tools
- `:callbacks` — callback functions for agent steps
- `:notify_pid` — PID to receive progress notifications
- `:hooks` — list of `Nous.Hook` structs for workflow lifecycle events
- `:pause_ref` — `:atomics` ref for on-demand pause signaling

## Returns

- `{:ok, final_state}` — workflow completed successfully
- `{:suspended, state, checkpoint}` — workflow paused
- `{:error, reason}` — workflow failed

---

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