Struct AxPlaybook 

pub struct AxPlaybook<S: AxAIClient, T: AxAIClient> { /* private fields */ }

A live, evolving context playbook bound to a program. Mirrors the TypeScript AxPlaybook: grow it offline from examples (evolve), keep it growing online from live feedback (update), render it into the program context (apply_to), and persist/restore it (to_json/load). The evolution engine (ACE) is hidden behind this surface, just as optimize() hides GEPA.

The bound program runs with the student client; the real reflector/curator are focused AxGen sub-programs driven by the teacher client. The program, the clients, the sub-programs, and the last prediction are held behind Rc<RefCell> so the generator/reflector/curator closures installed into AxACE can mutate them without statically aliasing the engine that owns those closures.

Implementations

impl<S: AxAIClient + 'static, T: AxAIClient + 'static> AxPlaybook<S, T>

pub fn new( program: AxGen, student: Rc<RefCell<S>>, teacher: Option<Rc<RefCell<T>>>, options: Value, ) -> Self

pub fn from_shared( program: Rc<RefCell<AxGen>>, student: Rc<RefCell<S>>, teacher: Option<Rc<RefCell<T>>>, options: Value, ) -> Self

Build a playbook that SHARES an already-Rc<RefCell>-wrapped program. Used by AxAgent::playbook() so the playbook injects its composed instruction straight into the live pipeline stage instead of a private clone.

pub fn evolve( &mut self, examples: &[Value], metric_fn: &mut dyn FnMut(&Value) -> Value, options: &Value, ) -> AxResult<Value>

Grow the playbook offline from labeled examples, scoring each rollout with metric_fn ({“prediction”, “example”}), then render the result into the bound program. Returns {bestScore, playbook}.

Examples found in repository

examples/ace_playbook.rs (line 61)

fn main() -> AxResult<()> {
    let mut program = ax("question:string -> answer:string")?;
    program.set_instruction("Answer the question.");

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = playbook(
        program,
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"maxEpochs": 1}),
    );

    let mut metric = |args: &Value| -> Value {
        let answer = args
            .get("prediction")
            .and_then(|p| p.get("answer"))
            .and_then(Value::as_str)
            .unwrap_or("");
        if answer.is_empty() {
            json!(0.0)
        } else {
            json!(1.0)
        }
    };

    let examples = vec![
        json!({"question": "What is Ax?"}),
        json!({"question": "Why typed signatures?"}),
    ];
    let result = pb.evolve(&examples, &mut metric, &json!({}))?;
    let rendered = pb.render();
    let state = pb.to_json();
    assert!(
        result.get("bestScore").is_some(),
        "missing bestScore: {result}"
    );
    assert!(state.get("playbook").is_some(), "missing playbook: {state}");
    assert!(state.get("artifact").is_some(), "missing artifact: {state}");
    println!("rendered: {rendered}");
    println!("rust-ace-playbook-ok");
    Ok(())
}

pub fn evolve_agent<C: AxAIClient>( &mut self, agent: &mut AxAgent, client: &mut C, dataset: &Value, options: &Value, ) -> AxResult<Value>

Verified agent-layer playbook learning from train/validation task sets. The agent is passed explicitly because Rust cannot safely store a self-reference inside the stage-bound playbook handle.

Examples found in repository

examples/agent_playbook.rs (lines 97-102)

fn main() -> AxResult<()> {
    // agent.playbook() binds an evolving context playbook to an agent stage. The
    // "responder" target grows the user-facing answer stage; ACE remains an
    // implementation detail behind playbook(), just as optimize() hides GEPA.
    let mut agent = agent_with_options(
        "question:string -> answer:string",
        json!({"name": "qa", "description": "Answer the question.", "runtime": {"language": "Python"}}),
    )?
    .with_runtime(Box::new(Runtime))?;

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = agent.playbook(
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"target": "responder", "maxEpochs": 1}),
    )?;

    let dataset = json!({"train": [{"input": {"question": "Answer briefly."}, "score": 0}]});
    let mut eval_client = ScriptedClient;

    // A zero minimum gain exercises verified acceptance. A positive minimum gain
    // rejects the same flat score and must restore the exact pre-proposal snapshot.
    let accepted = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let before_rejection = serde_json::to_string(&pb.to_json())?;
    let rejected = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0.1, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let after_rejection = serde_json::to_string(&pb.to_json())?;

    assert_eq!(
        accepted["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {accepted}"
    );
    assert_eq!(
        accepted["outcomes"][0]["accepted"].as_bool(),
        Some(true),
        "verified acceptance failed: {accepted}"
    );
    assert_eq!(
        rejected["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {rejected}"
    );
    assert_eq!(
        rejected["outcomes"][0]["accepted"].as_bool(),
        Some(false),
        "verified rejection failed: {rejected}"
    );
    assert_eq!(
        after_rejection, before_rejection,
        "rejected proposal was not rolled back exactly"
    );
    assert!(
        pb.to_json().get("playbook").is_some(),
        "missing playbook: {}",
        pb.to_json()
    );
    println!("accepted: {}", accepted["outcomes"][0]);
    println!("rejected: {}", rejected["outcomes"][0]);
    println!("rust-agent-playbook-ok");
    Ok(())
}

pub fn update(&mut self, args: &Value) -> AxResult<Value>

Refine the playbook online from a single live interaction. Safe to call without a prior evolve/load; the engine is hydrated lazily on first use.

pub fn apply_to(&mut self, program: Option<&mut AxGen>)

Render the current playbook into a program context (defaults to the bound program). When a different program is passed, its instruction is composed with the rendered playbook in place.

pub fn render(&self) -> String

Return the current playbook as a markdown block.

Examples found in repository

examples/ace_playbook.rs (line 62)

fn main() -> AxResult<()> {
    let mut program = ax("question:string -> answer:string")?;
    program.set_instruction("Answer the question.");

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = playbook(
        program,
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"maxEpochs": 1}),
    );

    let mut metric = |args: &Value| -> Value {
        let answer = args
            .get("prediction")
            .and_then(|p| p.get("answer"))
            .and_then(Value::as_str)
            .unwrap_or("");
        if answer.is_empty() {
            json!(0.0)
        } else {
            json!(1.0)
        }
    };

    let examples = vec![
        json!({"question": "What is Ax?"}),
        json!({"question": "Why typed signatures?"}),
    ];
    let result = pb.evolve(&examples, &mut metric, &json!({}))?;
    let rendered = pb.render();
    let state = pb.to_json();
    assert!(
        result.get("bestScore").is_some(),
        "missing bestScore: {result}"
    );
    assert!(state.get("playbook").is_some(), "missing playbook: {state}");
    assert!(state.get("artifact").is_some(), "missing artifact: {state}");
    println!("rendered: {rendered}");
    println!("rust-ace-playbook-ok");
    Ok(())
}

pub fn get_state(&self) -> Value

Return a serializable snapshot of the playbook and its history.

pub fn to_json(&self) -> Value

Alias for get_state.

Examples found in repository

examples/ace_playbook.rs (line 63)

fn main() -> AxResult<()> {
    let mut program = ax("question:string -> answer:string")?;
    program.set_instruction("Answer the question.");

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = playbook(
        program,
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"maxEpochs": 1}),
    );

    let mut metric = |args: &Value| -> Value {
        let answer = args
            .get("prediction")
            .and_then(|p| p.get("answer"))
            .and_then(Value::as_str)
            .unwrap_or("");
        if answer.is_empty() {
            json!(0.0)
        } else {
            json!(1.0)
        }
    };

    let examples = vec![
        json!({"question": "What is Ax?"}),
        json!({"question": "Why typed signatures?"}),
    ];
    let result = pb.evolve(&examples, &mut metric, &json!({}))?;
    let rendered = pb.render();
    let state = pb.to_json();
    assert!(
        result.get("bestScore").is_some(),
        "missing bestScore: {result}"
    );
    assert!(state.get("playbook").is_some(), "missing playbook: {state}");
    assert!(state.get("artifact").is_some(), "missing artifact: {state}");
    println!("rendered: {rendered}");
    println!("rust-ace-playbook-ok");
    Ok(())
}

examples/agent_playbook.rs (line 103)

fn main() -> AxResult<()> {
    // agent.playbook() binds an evolving context playbook to an agent stage. The
    // "responder" target grows the user-facing answer stage; ACE remains an
    // implementation detail behind playbook(), just as optimize() hides GEPA.
    let mut agent = agent_with_options(
        "question:string -> answer:string",
        json!({"name": "qa", "description": "Answer the question.", "runtime": {"language": "Python"}}),
    )?
    .with_runtime(Box::new(Runtime))?;

    let student = Rc::new(RefCell::new(ScriptedClient));
    let mut pb = agent.playbook(
        student,
        None::<Rc<RefCell<ScriptedClient>>>,
        json!({"target": "responder", "maxEpochs": 1}),
    )?;

    let dataset = json!({"train": [{"input": {"question": "Answer briefly."}, "score": 0}]});
    let mut eval_client = ScriptedClient;

    // A zero minimum gain exercises verified acceptance. A positive minimum gain
    // rejects the same flat score and must restore the exact pre-proposal snapshot.
    let accepted = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let before_rejection = serde_json::to_string(&pb.to_json())?;
    let rejected = pb.evolve_agent(
        &mut agent,
        &mut eval_client,
        &dataset,
        &json!({"verify": true, "minHeldInGain": 0.1, "maxProposals": 1, "maxMetricCalls": 2}),
    )?;
    let after_rejection = serde_json::to_string(&pb.to_json())?;

    assert_eq!(
        accepted["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {accepted}"
    );
    assert_eq!(
        accepted["outcomes"][0]["accepted"].as_bool(),
        Some(true),
        "verified acceptance failed: {accepted}"
    );
    assert_eq!(
        rejected["metricCallsUsed"].as_u64(),
        Some(2),
        "bad metric budget: {rejected}"
    );
    assert_eq!(
        rejected["outcomes"][0]["accepted"].as_bool(),
        Some(false),
        "verified rejection failed: {rejected}"
    );
    assert_eq!(
        after_rejection, before_rejection,
        "rejected proposal was not rolled back exactly"
    );
    assert!(
        pb.to_json().get("playbook").is_some(),
        "missing playbook: {}",
        pb.to_json()
    );
    println!("accepted: {}", accepted["outcomes"][0]);
    println!("rejected: {}", rejected["outcomes"][0]);
    println!("rust-agent-playbook-ok");
    Ok(())
}

pub fn load(&mut self, snapshot: &Value) -> &mut Self

Restore a snapshot into this handle and render it into the bound program.

pub fn configure_auto(&mut self, level: &str)

Set the evolution intensity preset ("light", "medium", or "heavy").

pub fn reset(&mut self)

Clear the playbook back to its initial state.

pub fn set_apply_hook(&mut self, hook: Box<dyn FnMut(&str)>)

Redirect playbook injection. Used to push the rendered playbook into a pipeline stage instead of the bound program.