# `Tune.Execution`
[🔗](https://github.com/mikehostetler/tune/blob/v0.5.0/lib/tune/execution.ex#L1)

Per-run state threaded through application program code.

It holds the program's named parameters, the fixed model configuration for
each role, the active role, the managed call allowance, the step limit, the
deadline, and every completed step and failed call. Application code passes
it through `predict/3` and `value/2` and returns the updated value.

All versions of the state share the run's call and response records.
Each call counts before dispatch, including calls that fail. Call
`predict/3` and `call_program/4` from the process running the program,
before its callback returns. Use evaluation concurrency to run independent
cases in parallel.

# `role`

```elixir
@type role() :: :target | :teacher | :proposal
```

# `t`

```elixir
@type t() :: %Tune.Execution{
  deadline: integer() | nil,
  journal: :ets.tid(),
  max_model_calls: non_neg_integer() | nil,
  max_steps: pos_integer(),
  models: %{optional(role()) =&gt; Tune.ModelConfig.t()},
  parameters: %{required(String.t()) =&gt; Tune.Predictor.t() | Tune.Parameter.t()},
  role: role(),
  scope: [String.t()]
}
```

# `call_program`

```elixir
@spec call_program(t(), term(), map(), keyword()) ::
  {:ok, map(), t()} | {:error, term(), t()}
```

Runs a nested program inside this execution.

The nested program uses its own parameters, the given role (default: the
active role), and this execution's allowance, step limit, and deadline.
Its steps are recorded under `scope`.

# `has_role?`

```elixir
@spec has_role?(t(), role()) :: boolean()
```

Returns `true` when a model configuration exists for the role.

# `predict`

```elixir
@spec predict(t(), String.t(), map()) :: {:ok, map(), t()} | {:error, term(), t()}
```

Calls the named predictor with the active role's model configuration.

Returns the validated output map and the updated execution, or an error and
the updated execution. The error is the original cause.

# `remaining_calls`

```elixir
@spec remaining_calls(t()) :: non_neg_integer() | nil
```

Returns the remaining managed call allowance, or `nil` when unlimited.

# `remaining_ms`

```elixir
@spec remaining_ms(t()) :: non_neg_integer() | nil
```

Returns milliseconds until the deadline, or `nil` without one.

# `roles`

```elixir
@spec roles() :: [role()]
```

Returns the managed roles.

# `steps`

```elixir
@spec steps(t()) :: [Tune.Step.t()]
```

Returns the completed steps in call order during the active program.

# `total_calls`

```elixir
@spec total_calls(t()) :: non_neg_integer()
```

Returns attempted managed calls across roles.

# `value`

```elixir
@spec value(t(), String.t()) :: {:ok, term()} | {:error, Exception.t()}
```

Reads a declared JSON parameter value. Makes no model call.

---

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