Struct Reasoner 

pub struct Reasoner<A> { /* private fields */ }

Holds candidate Actions and selects among them by utility.

Implementations

impl<A> Reasoner<A>

pub fn new() -> Reasoner<A>

Creates an empty reasoner.

Examples found in repository

examples/agent_brain.rs (line 15)

fn main() {
    // Signals about the current request, each normalized to 0.0..=1.0.
    let urgency = Score::from_ratio(80, 100);
    let confidence = Score::from_ratio(40, 100); // how well we already understand it
    let llm_available = true; // e.g. circuit breaker closed AND rate limiter has tokens

    let mut brain = Reasoner::new();

    // Answer from a template — strong when we are already confident.
    brain.add(Action::new("answer_template").consider_labeled(
        "confidence",
        Curve::Linear,
        confidence,
    ));

    // Escalate to the LLM — strong when urgent, but only if the LLM is available.
    brain.add(
        Action::new("call_llm")
            .gate(llm_available) // constraint-aware: skipped entirely if the LLM is down/limited
            .consider_labeled("urgency", Curve::Linear, urgency),
    );

    // An always-available, low-weight fallback so a decision still resolves.
    brain.add(Action::new("defer").with_base(Score::from_ratio(1, 10)));

    // Abstain if nothing clears the bar — the caller would escalate to a human.
    let threshold = Score::from_ratio(5, 100);
    match brain.decide_above(threshold) {
        Some(decision) => {
            println!(
                "chose: {} (utility {}/10000)",
                decision.id,
                decision.utility.raw()
            );
            if let Some(why) = brain.explain() {
                for c in why.contributions {
                    println!(
                        "  {} : input {} -> {}",
                        c.label,
                        c.input.raw(),
                        c.output.raw()
                    );
                }
            }
        }
        None => println!("nothing good enough — escalate to a human"),
    }
}

pub fn add(&mut self, action: Action<A>) -> &mut Self

Adds a candidate action.

Examples found in repository

examples/agent_brain.rs (lines 18-22)

fn main() {
    // Signals about the current request, each normalized to 0.0..=1.0.
    let urgency = Score::from_ratio(80, 100);
    let confidence = Score::from_ratio(40, 100); // how well we already understand it
    let llm_available = true; // e.g. circuit breaker closed AND rate limiter has tokens

    let mut brain = Reasoner::new();

    // Answer from a template — strong when we are already confident.
    brain.add(Action::new("answer_template").consider_labeled(
        "confidence",
        Curve::Linear,
        confidence,
    ));

    // Escalate to the LLM — strong when urgent, but only if the LLM is available.
    brain.add(
        Action::new("call_llm")
            .gate(llm_available) // constraint-aware: skipped entirely if the LLM is down/limited
            .consider_labeled("urgency", Curve::Linear, urgency),
    );

    // An always-available, low-weight fallback so a decision still resolves.
    brain.add(Action::new("defer").with_base(Score::from_ratio(1, 10)));

    // Abstain if nothing clears the bar — the caller would escalate to a human.
    let threshold = Score::from_ratio(5, 100);
    match brain.decide_above(threshold) {
        Some(decision) => {
            println!(
                "chose: {} (utility {}/10000)",
                decision.id,
                decision.utility.raw()
            );
            if let Some(why) = brain.explain() {
                for c in why.contributions {
                    println!(
                        "  {} : input {} -> {}",
                        c.label,
                        c.input.raw(),
                        c.output.raw()
                    );
                }
            }
        }
        None => println!("nothing good enough — escalate to a human"),
    }
}

pub fn len(&self) -> usize

Returns the number of candidate actions.

pub fn is_empty(&self) -> bool

Returns true if there are no candidate actions.

impl<A: Clone> Reasoner<A>

pub fn decide(&self) -> Option<Decision<A>>

Chooses the highest-utility action, or None if there are none.

Ties resolve deterministically in favor of the earlier-declared action, so the same candidates always yield the same decision.

pub fn decide_above(&self, threshold: Score) -> Option<Decision<A>>

Like decide, but abstains: returns the best action only when its utility is strictly above threshold, otherwise None.

Use it to say “nothing here is good enough” and fall back to a slower or more capable path — for example, escalate to an LLM instead of forcing a weak choice. A threshold of Score::ZERO abstains exactly when every action is vetoed or gated off.

Examples found in repository

examples/agent_brain.rs (line 36)

fn main() {
    // Signals about the current request, each normalized to 0.0..=1.0.
    let urgency = Score::from_ratio(80, 100);
    let confidence = Score::from_ratio(40, 100); // how well we already understand it
    let llm_available = true; // e.g. circuit breaker closed AND rate limiter has tokens

    let mut brain = Reasoner::new();

    // Answer from a template — strong when we are already confident.
    brain.add(Action::new("answer_template").consider_labeled(
        "confidence",
        Curve::Linear,
        confidence,
    ));

    // Escalate to the LLM — strong when urgent, but only if the LLM is available.
    brain.add(
        Action::new("call_llm")
            .gate(llm_available) // constraint-aware: skipped entirely if the LLM is down/limited
            .consider_labeled("urgency", Curve::Linear, urgency),
    );

    // An always-available, low-weight fallback so a decision still resolves.
    brain.add(Action::new("defer").with_base(Score::from_ratio(1, 10)));

    // Abstain if nothing clears the bar — the caller would escalate to a human.
    let threshold = Score::from_ratio(5, 100);
    match brain.decide_above(threshold) {
        Some(decision) => {
            println!(
                "chose: {} (utility {}/10000)",
                decision.id,
                decision.utility.raw()
            );
            if let Some(why) = brain.explain() {
                for c in why.contributions {
                    println!(
                        "  {} : input {} -> {}",
                        c.label,
                        c.input.raw(),
                        c.output.raw()
                    );
                }
            }
        }
        None => println!("nothing good enough — escalate to a human"),
    }
}

pub fn decide_weighted(&self, rand: u32) -> Option<Decision<A>>

Chooses an action at random with probability proportional to its utility (roulette selection), so repeated decisions vary instead of always returning the single best.

rand is any uniformly-distributed u32 you supply (e.g. from rand or getrandom), interpreted as the fraction rand / 2^32. The same rand and candidates always yield the same choice — the engine never owns a random source, so it stays deterministic and testable.

Returns None if there are no actions. If every utility is zero, the earliest-declared action is returned.

pub fn explain(&self) -> Option<Explanation<A>>

Explains the winning decision: the chosen id, its utility, and the per-consideration breakdown that produced it. None if there are no actions. The winner matches decide.

Examples found in repository

examples/agent_brain.rs (line 43)

fn main() {
    // Signals about the current request, each normalized to 0.0..=1.0.
    let urgency = Score::from_ratio(80, 100);
    let confidence = Score::from_ratio(40, 100); // how well we already understand it
    let llm_available = true; // e.g. circuit breaker closed AND rate limiter has tokens

    let mut brain = Reasoner::new();

    // Answer from a template — strong when we are already confident.
    brain.add(Action::new("answer_template").consider_labeled(
        "confidence",
        Curve::Linear,
        confidence,
    ));

    // Escalate to the LLM — strong when urgent, but only if the LLM is available.
    brain.add(
        Action::new("call_llm")
            .gate(llm_available) // constraint-aware: skipped entirely if the LLM is down/limited
            .consider_labeled("urgency", Curve::Linear, urgency),
    );

    // An always-available, low-weight fallback so a decision still resolves.
    brain.add(Action::new("defer").with_base(Score::from_ratio(1, 10)));

    // Abstain if nothing clears the bar — the caller would escalate to a human.
    let threshold = Score::from_ratio(5, 100);
    match brain.decide_above(threshold) {
        Some(decision) => {
            println!(
                "chose: {} (utility {}/10000)",
                decision.id,
                decision.utility.raw()
            );
            if let Some(why) = brain.explain() {
                for c in why.contributions {
                    println!(
                        "  {} : input {} -> {}",
                        c.label,
                        c.input.raw(),
                        c.output.raw()
                    );
                }
            }
        }
        None => println!("nothing good enough — escalate to a human"),
    }
}

pub fn rank(&self) -> Vec<Decision<A>>

Returns every action ranked by utility, highest first.

The sort is stable, so ties keep declaration order and the ranking is deterministic.

Trait Implementations

impl<A: Clone> Clone for Reasoner<A>

fn clone(&self) -> Reasoner<A>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Debug> Debug for Reasoner<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A> Default for Reasoner<A>

fn default() -> Self

Returns the “default value” for a type.