Struct Action 

#[non_exhaustive]
pub struct Action<A> {
    pub id: A,
    pub base: Score,
    pub allowed: bool,
    pub considerations: Vec<Consideration>,
}

A candidate decision: the value returned if chosen, plus the considerations that score it.

Utility is the base weight multiplied by every consideration. Because they multiply, any near-zero consideration vetoes the action — all of them must be satisfied for a high utility.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: A

The value returned when this action is chosen.

base: Score

The base weight before considerations (defaults to Score::MAX).

allowed: bool

Whether this action is permitted. A gated-off action (false) always has zero utility, so it is never chosen by decide/decide_weighted. Set it with gate. Defaults to true.

considerations: Vec<Consideration>

The considerations multiplied together to form the utility.

Implementations

impl<A> Action<A>

pub fn new(id: A) -> Action<A>

Creates an action with a neutral base weight and no considerations.

Examples found in repository

examples/agent_brain.rs (line 18)

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 gate(self, allowed: bool) -> Action<A>

Gates the action on a caller-supplied condition (builder style). Calls combine with AND, so .gate(a).gate(b) is allowed only when both hold.

This is how decisions become constraint-aware without any dependency: the caller passes whatever it already knows — a deadline, a rate limiter, a circuit breaker, business hours, a feature flag — as a bool. A gated-off action has zero utility and is never chosen. Keep one ungated fallback action so a decision still resolves when everything else is gated off.

Examples found in repository

examples/agent_brain.rs (line 27)

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 with_base(self, base: Score) -> Action<A>

Sets the base weight (builder style).

Examples found in repository

examples/agent_brain.rs (line 32)

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 consider(self, curve: Curve, input: Score) -> Action<A>

Adds a consideration (builder style).

pub fn consider_labeled( self, label: &'static str, curve: Curve, input: Score, ) -> Action<A>

Adds a labeled consideration (builder style); the label appears in Reasoner::explain output.

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 utility(&self) -> Score

Computes the action’s utility: base * product(considerations), or Score::ZERO if the action is gated off (allowed is false).

Trait Implementations

impl<A: Clone> Clone for Action<A>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<A: Debug> Debug for Action<A>

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

Formats the value using the given formatter.