evoproc_procedures.runners

Step executors for global-state procedures.

This module executes a Procedure (as JSON/dict) step-by-step by:

  1. Assembling the visible inputs for each step from the global state,

  2. Building an execution prompt with evo_proc_procedures.prompts.create_execution_prompt(),

  3. Calling a provided query_fn (LLM backend) with a JSON Schema for the step’s outputs,

  4. Parsing and merging returned outputs back into the global state.

Design

  • Backend-agnostic: pass any query_fn(prompt, model, fmt, seed) -> str.

  • Strict by default: raises if a required output is missing.

  • Final step uses your answer_schema (e.g., GSM/ARC) instead of a generic schema.

Typical usage

>>> from evoproc_procedures.runners import run_steps_stateful_minimal
>>> from evoproc_procedures.query_backends.ollama import query
>>> state = run_steps_stateful_minimal(proc, "2+3=?", gsm_schema, "gemma3:latest", query_fn=query)
>>> state["final_answer"]

Functions

create_output_schema(step)

Create a permissive JSON Schema for this step's declared outputs.

run_steps_stateful_minimal(proc, ...[, ...])

Execute a global-state procedure and return the final state.
evoproc_procedures.runners.create_output_schema(step)[source]

Create a permissive JSON Schema for this step’s declared outputs.

The schema enforces keys and presence (required), but allows the value type to be number/string/boolean. Use a stricter schema if your step needs it.

Parameters:

step (Mapping[str, Any]) – A step object with an "output" list of field dicts (each dict must include {"name": ..., "description": ...}).

Returns:

JSON Schema enforcing required output keys and simple scalar types.

Return type:

dict

evoproc_procedures.runners.run_steps_stateful_minimal(proc, problem_text, answer_schema, model, *, query_fn=None, seed=1234, print_bool=False, strict_missing=True)[source]

Execute a global-state procedure and return the final state.

For each step, this:

  • Collects only the needed inputs from the current global state,

  • Builds an execution prompt and a strict JSON Schema for outputs,

  • Calls query_fn to obtain a JSON object,

  • Merges declared outputs back into the global state.

The final step uses answer_schema (e.g., GSM/ARC) so you can grade results.

Parameters:

  • proc (Mapping[str, Any]) – Procedure JSON with keys: "steps" (list), and step fields including "id", "inputs" (list of fields), "stepDescription", and "output".

  • problem_text (str) – The original task text; becomes state["problem_text"] and must be the only input of Step 1 per global-state rules.

  • answer_schema (Dict[str, Any]) – JSON Schema dict for the final step’s output object.

  • model (str) – Backend model name passed to query_fn.

  • query_fn (Optional[Callable[[str, str, Optional[Dict[str, Any]], Optional[int]], str]]) – Callable with signature (prompt, model, fmt, seed) -> str. If omitted, we lazily import Ollama’s default query (requires evoproc_procedures[llm]).

  • seed (Optional[int]) – Optional random seed for the backend (if supported).

  • print_bool (bool) – If True, prints visible inputs and outputs for each step (debugging).

  • strict_missing (bool) – If True, raises when the model omits a required output key; if False, leaves it unset.

Returns:

The final global state containing all produced variables (including final_answer).

Return type:

dict

Raises:

  • RuntimeError – If a step input cannot be resolved from the global state, or a required output is missing and strict_missing=True.

  • ValueError – If the backend response is not valid JSON.