# `Orchid`
[🔗](https://github.com/SynapticStrings/Orchid/blob/main/lib/orchid.ex#L1)

The core entry point for the Orchid workflow engine.

This module provides the primary interface (`run/3`) to execute defined Recipes.
It is designed to be a flexible and extensible framework for task orchestration.

# `run`
[🔗](https://github.com/SynapticStrings/Orchid/blob/main/lib/orchid.ex#L46)

```elixir
@spec run(
  Orchid.Recipe.t() | [Orchid.Step.t()],
  Orchid.Scheduler.initial_params(),
  keyword()
) ::
  Orchid.Operon.Response.payload() | Orchid.Operon.Response.t()
```

Executes a workflow Recipe.

It initializes the pipeline, injects any configured middleware (Operons), and
starts the execution process.

### Options

* `:return_response` - (boolean) If `true`, returns the full `Orchid.Operon.Response` struct
  (which includes assigns and metadata) instead of just the result payload. Defaults to `false`.
* `:operons_stack` - (list) A list of additional middleware modules (Recipe-level hooks)
  to run before the execution phase. They are executed in the order provided.
* `:global_hooks_stack` - (list)
* `:executor_and_opts` - (tuple) Executor module and its options.
* `:core_hook` - (module) A Module for execute step.
* `:baggage` - (enumerable) Custom options used by user/custome operons/hooks/etc.

### Examples

    # Normal execution returning {:ok, results}
    Orchid.run(my_recipe, initial_params)

    # Execution returning the full Response struct
    Orchid.run(my_recipe, initial_params, return_response: true)

# `run_with_ctx`
[🔗](https://github.com/SynapticStrings/Orchid/blob/main/lib/orchid.ex#L60)

```elixir
@spec run_with_ctx(
  Orchid.Recipe.t() | [Orchid.Step.t()],
  Orchid.Scheduler.initial_params(),
  Orchid.WorkflowCtx.t()
) :: Orchid.Operon.Response.payload() | Orchid.Operon.Response.t()
```

Run with explicit WorkflowContext struct.

---

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