Struct Engine 

pub struct Engine { /* private fields */ }

The main engine. Owns item registry, user states, factor pipeline, selector.

Usage

use aria_core::{Engine, EngineConfig, Signal, Scoreable};
use aria_core::item::Item;
use aria_core::factor::{ChallengeFactor, SpacingFactor, CoverageFactor};

let mut engine = Engine::new(EngineConfig::default());

engine.add_factor(Box::new(ChallengeFactor::default()));
engine.add_factor(Box::new(SpacingFactor::default()));
engine.add_factor(Box::new(CoverageFactor));

engine.add_items(vec![
    Item::new("algebra_basics", 0.2, "algebra"),
    Item::new("quadratic_eq",   0.6, "algebra"),
    Item::new("integration",    0.9, "calculus"),
]).unwrap();

let item = engine.suggest("user_42").unwrap();
let item_id = item.id().to_string();
engine.feedback("user_42", &item_id, Signal::new(true, 0.4)).unwrap();

Implementations

impl Engine

pub fn new(config: EngineConfig) -> Self

Create engine with config.

Examples found in repository

examples/learning_simulation.rs (lines 16-19)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

/// Quick demo showing the same engine used for a completely different domain.
fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}

pub fn set_updater(&mut self, updater: Box<dyn StateUpdater>)

Replace the default state updater with a custom implementation. Call before first interaction.

pub fn add_items(&mut self, items: Vec<Item>) -> Result<(), AriaError>

Register items. Returns Err if prerequisites form a cycle.

Examples found in repository

examples/learning_simulation.rs (lines 28-46)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

/// Quick demo showing the same engine used for a completely different domain.
fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}

pub fn add_factor(&mut self, factor: Box<dyn Factor>)

Register a scoring factor. Order matters — factors are applied in registration order; all scores are multiplied together.

Examples found in repository

examples/learning_simulation.rs (line 22)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

/// Quick demo showing the same engine used for a completely different domain.
fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}

pub fn suggest(&mut self, user_id: &str) -> Result<&Item, AriaError>

Suggest the best next item for a user.

Creates a fresh ProfileState for new users automatically. Returns a reference to the winning Item.

Examples found in repository

examples/learning_simulation.rs (line 76)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

/// Quick demo showing the same engine used for a completely different domain.
fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}

pub fn feedback( &mut self, user_id: &str, item_id: &str, signal: Signal, ) -> Result<(), AriaError>

Report feedback for a user-item interaction. Updates internal ProfileState for the user.

Examples found in repository

examples/learning_simulation.rs (line 80)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

/// Quick demo showing the same engine used for a completely different domain.
fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}

pub fn get_state(&self, user_id: &str) -> Option<&ProfileState>

Get current ProfileState for a user. Returns None if user has no interactions.

Examples found in repository

examples/learning_simulation.rs (line 82)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

pub fn load_state(&mut self, user_id: impl Into<String>, state: ProfileState)

Load a previously serialised ProfileState for a user. Use with Serialiser::decode to restore sessions across restarts.

Examples found in repository

examples/learning_simulation.rs (line 165)

fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}

pub fn item_count(&self) -> usize

Number of registered items.

Examples found in repository

examples/learning_simulation.rs (line 48)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

pub fn factor_count(&self) -> usize

Number of registered factors.

Examples found in repository

examples/learning_simulation.rs (line 49)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

pub fn seed_rng(&mut self, seed: u64)

Seed the selector RNG — use in tests for determinism.

Examples found in repository

examples/learning_simulation.rs (line 25)

fn main() {
    println!("=== aria-core: Learning Domain Simulation ===\n");

    // --- Build engine ---
    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0, // deterministic for demo
        alpha: 0.1,            // faster skill movement so visible in 15 steps
    });

    // Register factors — caller's choice
    engine.add_factor(Box::new(ChallengeFactor::new(0.2)));
    engine.add_factor(Box::new(SpacingFactor::new(10))); // 10s interval for demo
    engine.add_factor(Box::new(CoverageFactor));
    engine.seed_rng(42);

    // Register items — caller's curriculum
    engine.add_items(vec![
        // Math track
        Item::new("counting",        0.05, "math"),
        Item::new("addition",        0.15, "math"),
        Item::new("multiplication",  0.30, "math"),
        Item::new("fractions",       0.45, "math"),
        Item::new("algebra_basics",  0.60, "math"),
        Item::new("quadratics",      0.75, "math")
            .with_prereqs(vec!["algebra_basics".into()]),
        Item::new("calculus_intro",  0.90, "math")
            .with_prereqs(vec!["quadratics".into()]),

        // Science track (no prereqs — runs in parallel)
        Item::new("sci_observation", 0.10, "science"),
        Item::new("sci_hypothesis",  0.25, "science"),
        Item::new("sci_experiment",  0.50, "science"),
        Item::new("sci_analysis",    0.70, "science"),
        Item::new("sci_research",    0.90, "science"),
    ]).unwrap();

    println!("Items registered: {}", engine.item_count());
    println!("Factors registered: {}\n", engine.factor_count());

    println!("{:<5} {:<22} {:<10} {:<8} {:<8} {:<10}",
        "Step", "Item", "Category", "Success", "Effort", "Skill");
    println!("{}", "-".repeat(70));

    // --- Simulate 15 interactions ---
    // Alternates easy successes and a few failures to show adaptation
    let interactions: Vec<(bool, f32)> = vec![
        (true,  0.8),  // 1  hard success
        (true,  0.3),  // 2  easy success → optimism up
        (true,  0.2),  // 3  easy
        (false, 0.9),  // 4  failure → optimism eases
        (true,  0.5),  // 5
        (true,  0.4),  // 6
        (true,  0.2),  // 7  easy → optimism climbs
        (true,  0.3),  // 8
        (false, 0.7),  // 9  failure
        (true,  0.5),  // 10
        (true,  0.4),  // 11
        (true,  0.3),  // 12
        (true,  0.2),  // 13
        (true,  0.5),  // 14
        (true,  0.3),  // 15
    ];

    for (step, (success, effort)) in interactions.iter().enumerate() {
        let item = engine.suggest("alice").unwrap();
        let item_id = item.id().to_string();
        let category = item.category().to_string();

        engine.feedback("alice", &item_id, Signal::new(*success, *effort)).unwrap();

        let state = engine.get_state("alice").unwrap();
        println!("{:<5} {:<22} {:<10} {:<8} {:<8.2} {:<.4}",
            step + 1,
            item_id,
            category,
            if *success { "✓" } else { "✗" },
            effort,
            state.skill,
        );
    }

    // --- Show final state ---
    let state = engine.get_state("alice").unwrap();
    println!("\n=== Final State ===");
    println!("Skill:             {:.4}", state.skill);
    println!("Optimism bias:     {:.4}", state.optimism_bias);
    println!("Target:            {:.4}", state.target());
    println!("Interactions:      {}", state.interaction_count);
    println!("Resolved items:    {:?}", state.resolved_set);

    println!("\n=== Category Coverage ===");
    let mut cats: Vec<_> = state.category_count.iter().collect();
    cats.sort_by_key(|(k, _)| k.as_str());
    for (cat, count) in cats {
        println!("  {:<12} → {} interactions", cat, count);
    }

    // --- Serialise / deserialise round-trip ---
    println!("\n=== Serialisation Round-Trip ===");
    let encoded = Serialiser::encode(state);
    println!("Encoded keys: {}", encoded.len());
    let decoded = Serialiser::decode(&encoded).unwrap();
    assert!((decoded.skill - state.skill).abs() < 1e-5, "skill mismatch after round-trip");
    assert_eq!(decoded.interaction_count, state.interaction_count);
    println!("Round-trip: ✓ skill={:.4} interactions={}", decoded.skill, decoded.interaction_count);

    // --- Prereq demonstration ---
    println!("\n=== Prerequisite Gating ===");
    println!("calculus_intro requires: quadratics → algebra_basics");
    let can_see_calculus = state.resolved_set.contains("quadratics");
    println!("User resolved quadratics: {}", can_see_calculus);
    println!("(calculus_intro will unlock once quadratics is resolved)");

    println!("\n=== Custom Domain Example (ecommerce) ===");
    demo_ecommerce();
}

/// Quick demo showing the same engine used for a completely different domain.
fn demo_ecommerce() {
    use aria_core::factor::ChallengeFactor;

    struct BudgetFactor;
    impl aria_core::factor::Factor for BudgetFactor {
        fn name(&self) -> &str { "budget" }
        fn score(&self, item: &dyn Scoreable, state: &aria_core::ProfileState, _now: u64) -> f32 {
            // score_proxy = price_ratio (0=free, 1=most expensive)
            // ProfileState.skill = budget_willingness
            let target = state.target();
            let diff = item.score_proxy() - target;
            (-diff * diff / 0.08).exp() // bandwidth=0.2
        }
    }

    let mut engine = Engine::new(EngineConfig {
        exploration_rate: 0.0,
        alpha: 0.1,
    });
    engine.add_factor(Box::new(BudgetFactor));
    engine.add_factor(Box::new(ChallengeFactor::new(0.25))); // reused as price-fit
    engine.seed_rng(1);

    engine.add_items(vec![
        Item::new("budget_headphones",  0.1, "audio"),
        Item::new("mid_headphones",     0.4, "audio"),
        Item::new("premium_headphones", 0.9, "audio"),
        Item::new("budget_speaker",     0.15, "audio"),
        Item::new("smartwatch_basic",   0.3, "wearables"),
        Item::new("smartwatch_pro",     0.8, "wearables"),
    ]).unwrap();

    // User with mid budget
    let mut state = aria_core::ProfileState::new();
    state.skill = 0.35; // budget willingness
    engine.load_state("shopper", state);

    print!("Suggestions for mid-budget shopper: ");
    for _ in 0..3 {
        let item = engine.suggest("shopper").unwrap();
        let id = item.id().to_string();
        print!("{} ", id);
        engine.feedback("shopper", &id, Signal::new(true, 0.5)).unwrap();
    }
    println!();
}