State

After an optimizer tunes a module, the improved instructions and demos live only in memory. ModuleState snapshots the mutable state of every Predict leaf in a module into a serializable value, so an optimized program can be saved to disk and reloaded in production without re-running optimization.

// After optimization:
ModuleState::from_module(&module)?.save("optimized.json")?;

// In production:
let mut module = MyPipeline::new();
ModuleState::load("optimized.json")?.apply(&mut module)?;

`ModuleState`

A ModuleState holds one PredictState per predictor, keyed by the leaf name the module declares via Predictors (predictors: BTreeMap<String, PredictState>). The BTreeMap keeps JSON output stable across runs. The names are the same ones optimizer candidates and trace spans use — one naming contract across persistence, optimization, and capture.

Method	Signature	Behavior
`from_module`	`fn from_module<M: Predictors + ?Sized>(module: &M) -> Result<Self>`	Snapshots every declared `Predict` leaf (instruction override + demos).
`apply`	`fn apply<M: Predictors + ?Sized>(&self, module: &mut M) -> Result<()>`	Applies the state in place, stamping each restored leaf’s trace name with its declared name. Every name in the state must resolve to a leaf in the module; unknown names are an error. Predictors not named in the state are left untouched.
`to_json`	`fn to_json(&self) -> Result<String>`	Serializes to pretty-printed JSON.
`from_json`	`fn from_json(json: &str) -> Result<Self>`	Deserializes JSON produced by `to_json`.
`save`	`fn save(&self, path: impl AsRef<Path>) -> Result<()>`	Writes `to_json` output to a file.
`load`	`fn load(path: impl AsRef<Path>) -> Result<Self>`	Reads a file written by `save`.

`PredictState` and the JSON shape

PredictState is the serializable snapshot of a single predictor’s mutable state.

Field	Type	Meaning
`demos`	`Vec<JsonMap>`	Demo rows as flat JSON objects: field name to value, with input and output fields merged into one object. Rows are split back into the predictor’s typed `Demo<S>` via the signature schema on load.
`instruction_override`	`Option<String>`	The instruction override, if any. `null` means the signature default applies.

A saved file therefore looks like:

{
  "predictors": {
    "answerer": {
      "demos": [
        { "question": "2+2?", "answer": "4" }
      ],
      "instruction_override": "Answer concisely."
    }
  }
}

The install seam

State loading reaches predictors through the object-safe per-leaf view PredictorInfo (see Modules). Its load_state method is the install seam: a full overwrite of the leaf’s optimizable state (instruction_override: None clears the override, demos replaces the demo set), used by ModuleState::apply and by the optimizer’s one-shot install of the winning candidate. Candidate evaluation never calls it — candidates are injected ambiently per call tree (see Optimizers). Every load_state invalidates the leaf’s cached instance overlay, so a candidate is data applied through the seam, never ad hoc field mutation.

Compatibility behavior

There is no version field in the format. Compatibility is field level and structural:

Situation	Result
Missing `demos` or `instruction_override` in JSON	Defaults apply (`serde(default)` on both fields).
State names a leaf absent from the module	`apply` returns an error listing the unknown predictors.
Demo rows do not fit the predictor’s signature schema	`apply` returns `failed to load state for` name“.
Module has predictors the state does not name	Left untouched, no error.

Get Started

Building Blocks

Programs as Data

Tools & Agents

Evaluation & Optimization

Utilities

`ModuleState`

`PredictState` and the JSON shape

The install seam

Compatibility behavior

See also

​ModuleState

​PredictState and the JSON shape

​The install seam

​Compatibility behavior

​See also

`ModuleState`

`PredictState` and the JSON shape

The install seam

Compatibility behavior

See also