RuntimeParams

use horus::prelude::*;

let params = RuntimeParams::new()?;

// Typed get with default
let speed: f64 = params.get_or("max_speed", 1.0);

// Typed set
params.set("max_speed", 2.0)?;

// Check and iterate
if params.has("pid_kp") {
    let keys = params.list_keys();
    println!("Parameters: {:?}", keys);
}

// Persist to disk
params.save_to_disk()?;

// Load from .horus/config/params.yaml (or built-in defaults)
let params = RuntimeParams::new()?;

// Load from explicit file
let params = RuntimeParams::new()?;
params.load_from_disk(Path::new("config/robot.yaml"))?;

// Option-based (returns None if missing or type mismatch)
let speed: Option<f64> = params.get("max_speed");

// With default value
let kp: f64 = params.get_or("pid_kp", 1.0);

// With explicit error reporting
let speed: f64 = params.get_typed("max_speed")?;  // Returns HorusError if missing

// Check existence
if params.has("emergency_stop_distance") {
    // ...
}

// Set any serde-serializable value
params.set("max_speed", 1.5_f64)?;
params.set("sensor_ids", vec![1, 2, 3])?;
params.set("robot_name", "atlas")?;

// Optimistic locking (concurrent edit protection)
let version = params.get_version("max_speed");
params.set_with_version("max_speed", 2.0, version)?;  // Fails if modified since

// Remove a parameter
params.remove("obsolete_param");

// Reset to defaults
params.reset()?;

// Save current state to .horus/config/params.yaml
params.save_to_disk()?;

// Load from specific file
params.load_from_disk(Path::new("config/prod.yaml"))?;

use horus::prelude::*;

struct MotorController {
    params: RuntimeParams,
}

impl MotorController {
    fn new() -> Result<Self> {
        Ok(Self {
            params: RuntimeParams::new()?,
        })
    }
}

impl Node for MotorController {
    fn name(&self) -> &str { "motor_ctrl" }

    fn tick(&mut self) {
        let kp: f64 = self.params.get_or("pid_kp", 1.0);
        let max_speed: f64 = self.params.get_or("max_speed", 1.0);
        // ... use params in control loop
    }
}

import horus

p = horus.Params()
kp = p["pid_kp"]        # 1.0
p["pid_kp"] = 2.5
p.save()

use horus::prelude::*;

// PID gain with range validation
// If metadata exists with Range(0.0, 100.0), this fails:
let result = params.set("pid.kp", 150.0);
// Err: "Parameter 'pid.kp' value 150 exceeds maximum 100"

// Enum-validated parameter
let result = params.set("mode", "turbo");
// Err: "Parameter 'mode' value 'turbo' not in allowed values: [manual, auto, standby]"

// Query metadata for a parameter
if let Some(meta) = params.get_metadata("max_speed") {
    println!("Description: {:?}", meta.description);
    println!("Unit: {:?}", meta.unit);
    println!("Read-only: {}", meta.read_only());
}

use horus::prelude::*;

// Read current version
let version = params.get_version("pid.kp");

// Set with version check — fails if someone else modified it since our read
match params.set_with_version("pid.kp", 2.5, version) {
    Ok(()) => println!("Updated successfully"),
    Err(e) => println!("Conflict: {}", e), // Someone else changed it
}

// Save all parameters to disk (uses default path)
params.save_to_disk()?;

// Load parameters from a specific file
params.load_from_disk(Path::new("robot_config.yaml"))?;

pid.kp: 2.5
pid.ki: 0.1
pid.kd: 0.05
max_speed: 1.0
mode: "auto"

pub fn new() -> HorusResult<Self>

let params = RuntimeParams::new()?;

pub fn get<T: Deserialize>(&self, key: &str) -> Option<T>

let speed: Option<f64> = params.get("max_speed");

pub fn get_typed<T: Deserialize>(&self, key: &str) -> HorusResult<T>

let kp: f64 = params.get_typed("pid_kp")?; // error if missing

pub fn get_or<T: Deserialize>(&self, key: &str, default: T) -> T

let speed = params.get_or("max_speed", 1.5); // 1.5 if not set

pub fn set<T: Serialize>(&self, key: &str, value: T) -> Result<(), HorusError>

params.set("pid_kp", 2.5)?;
params.set("max_speed", 0.8)?;

pub fn set_with_version<T: Serialize>(&self, key: &str, value: T, expected_version: u64) -> Result<(), HorusError>

let version = params.get_version("pid_kp");
// ... compute new value ...
params.set_with_version("pid_kp", new_kp, version)?; // fails if someone else changed it

pub fn list_keys(&self) -> Vec<String>

for key in params.list_keys() {
    println!("{} = {:?}", key, params.get::<serde_json::Value>(&key));
}

pub fn has(&self, key: &str) -> bool

pub fn remove(&self, key: &str) -> Option<Value>

pub fn reset(&self) -> Result<(), HorusError>

pub fn get_metadata(&self, key: &str) -> Option<ParamMetadata>

if let Some(meta) = params.get_metadata("max_speed") {
    println!("Unit: {:?}, Read-only: {}", meta.unit, meta.read_only);
}

pub fn get_version(&self, key: &str) -> u64