Recursive Decision Patterns

Fast typed decisions become more useful when one result defines the next question. TypeSafeSDK 0.4.0 documents these patterns explicitly; the SDK does not introduce a separate workflow engine. Use ordinary functions, TypeSafeSDK.evaluate/4, Prepared, cancellation, supervisors, or TypeSafeSDK.OTP.Server as appropriate.

These patterns were informed in part by the recursive-workflow examples in dannote/jev. The implementations below retain TypeSafeSDK's bounded/runtime separation rather than copying Jev's transport.

Hierarchical descent

For a classification space larger than one Choice request should reasonably contain, ask one level at a time. The selected child narrows the next Choice. Always enforce an application-owned depth bound and confidence policy.

def descend(client, state, node, depth, max_depth) when depth < max_depth do
  children = children(node)

  if length(children) < 2 do
    {:ok, node}
  else
    options =
      children
      |> Enum.with_index()
      |> Enum.map(fn {child, index} -> {Integer.to_string(index), summary(child)} end)

    with {:ok, response} <-
           TypeSafeSDK.evaluate(client, state,
             child: TypeSafeSDK.choice("Which child is the best match?", options)
           ),
         answer <- TypeSafeSDK.Response.fetch!(response, :child),
         :act <- TypeSafeSDK.Answer.gate(answer, act: 0.85, review: 0.65),
         {index, ""} <- Integer.parse(answer.choice) do
      descend(client, state, Enum.at(children, index), depth + 1, max_depth)
    else
      _ -> {:ok, node}
    end
  end
end

Bisection

Search large text or ordered spaces in logarithmic rounds rather than scoring every element. Ask about both halves in one evaluation, recurse only into halves that pass an explicit threshold, and stop when the chunk reaches a deterministic size bound. If both halves qualify, use a supervisor or bounded batch to explore them concurrently rather than spawning unbounded tasks.

Verify and repair

For extraction from a finite candidate set, separate selection from verification:

1. choose one candidate per field;
2. ask a Noul verification question where true means the candidate is wrong;
3. remove rejected candidates;
4. repeat only the failed fields.

The shrinking candidate set gives the workflow a structural termination bound. Also keep an explicit round limit for malformed data and treat exhausted candidate sets as deterministic failures instead of asking indefinitely.

Coarse-to-fine cascade

Ask a broad, cheap question first. If the response does not meet the application's confidence/margin requirement, construct a narrower Choice from the strongest remaining candidates and optionally select a different model for the second call. Do not encode universal confidence thresholds in the SDK; tune them from labeled development data and freeze policy before held-out evaluation.

Clarifying conversations

When a decision is not strong enough to act, the application can ask the human a clarifying question, append the reply to application state, and evaluate the same intent again. Bound the number of turns and persist conversational state outside a transient GenServer when losing a turn would be unacceptable.

Recursive OTP workflows

TypeSafeSDK.OTP.Server can express the same loop by returning another {:evaluate, ...} from handle_evaluation/3. Its max_in_flight bound applies to the whole server, so recursive fan-out cannot silently create unlimited local workers. For durable or distributed workflows, use the application's existing workflow/supervision system and keep TypeSafeSDK as the decision primitive.

Runnable live patterns

mix run examples/live_recursive_decisions.exs executes all five patterns above against the selected real endpoint: two-level hierarchical descent, two-round bisection, verify/repair with a shrinking candidate set, a coarse-to-fine cascade, and a clarifying conversation capped at two turns. The script has a hard upper bound of 12 API requests and reports its actual request count. No branch substitutes canned model outputs or a fake fallback.

For recursion inside the OTP facade, mix run examples/live_otp_server.exs launches a bounded follow-up evaluation from handle_evaluation/3.