jelq

//! Where the game's decisions come from. The seeded rng is the default; an

//! operator can instead point the server at a System One service and let the

//! model answer every roll over HTTP (JELQD_ORACLE=clm).

//!

//! Identity randomness (run ids, etag salts, nonces) never goes to the model.

//! The Clm arm carries its own rng for those, seeded like the rng arm's.

use rand::{Rng, SeedableRng, rngs::StdRng};

use serde_json::{Value, json};

/// One named decision. The state prose is what the model reads as context, the

/// ask is the question, and the site is a stable name for logs and caching.

pub(crate) struct Roll {

    pub(crate) state: String,

    pub(crate) site: &'static str,

    pub(crate) ask: String,

}

pub(crate) enum Oracle {

    Rng(StdRng),

    Clm { clm: Clm, technical: StdRng },

}

pub(crate) enum OracleTemplate {

    Rng,

    Clm { url: String },

}

pub(crate) struct Clm {

    url: String,

    agent: ureq::Agent,

}

impl Oracle {

    pub(crate) fn build(template: &OracleTemplate, seed: u64) -> Self {

        match template {

            OracleTemplate::Rng => Self::Rng(StdRng::seed_from_u64(seed)),

            OracleTemplate::Clm { url } => Self::Clm {

                clm: Clm::new(url),

                technical: StdRng::seed_from_u64(seed),

            },

        }

    }

    fn technical(&mut self) -> &mut StdRng {

        match self {

            Self::Rng(rng) => rng,

            Self::Clm { technical, .. } => technical,

        }

    }

    /// Identity randomness, never a game decision.

    pub(crate) fn u64(&mut self) -> u64 {

        self.technical().random()

    }

    /// A yes/no game roll with stated odds of 1 in `odds`.

    pub(crate) fn chance(&mut self, roll: Roll, odds: u32) -> bool {

        match self {

            Self::Rng(rng) => rng.random_ratio(1, odds),

            Self::Clm { clm, .. } => {

                let ask = format!("{}, with odds of 1 in {odds}.", roll.ask);

                clm.decide(&roll.state, roll.site, &ask) > 0.5

            }

        }

    }

    /// A yes/no game roll where the ask describes the calm outcome, not the

    /// event. The model believes dull statements more readily than rare

    /// warnings, so the interrupts that read as drama get phrased as calm.

    /// The rng arm still draws the event, never the calm.

    pub(crate) fn chance_not(&mut self, roll: Roll, odds: u32) -> bool {

        match self {

            Self::Rng(rng) => rng.random_ratio(1, odds),

            Self::Clm { clm, .. } => {

                let ask = format!("{}, with odds of 1 in {odds}.", roll.ask);

                clm.decide(&roll.state, roll.site, &ask) <= 0.5

            }

        }

    }

    /// A yes/no game roll with general odds of `num` in `den`, put to the

    /// model as a choice between the calm answer and the event. The noul head

    /// answers interrupt questions with yes; the choice head, offered the two

    /// answers side by side, does not.

    pub(crate) fn ratio_choice(

        &mut self,

        roll: Roll,

        num: u32,

        den: u32,

        calm: &str,

        event: &str,

    ) -> bool {

        match self {

            Self::Rng(rng) => rng.random_ratio(num, den),

            Self::Clm { clm, .. } => {

                let i = clm.choose(&roll.state, roll.site, &roll.ask, &[calm, event]);

                i == 1

            }

        }

    }

    /// A yes/no game roll with general odds of `num` in `den`.

    pub(crate) fn ratio(&mut self, roll: Roll, num: u32, den: u32) -> bool {

        match self {

            Self::Rng(rng) => rng.random_ratio(num, den),

            Self::Clm { clm, .. } => {

                let ask = format!("{}, with odds of about {num} in {den}.", roll.ask);

                clm.decide(&roll.state, roll.site, &ask) > 0.5

            }

        }

    }

    /// One bucket chosen by weighted draw. The rng arm draws by `weights` and

    /// ignores the descriptions; the clm arm reads them all and picks the one

    /// the model believes, weights unused.

    pub(crate) fn pick(&mut self, roll: Roll, weights: &[u32], options: &[&str]) -> usize {

        match self {

            Self::Rng(rng) => {

                let total: u32 = weights.iter().sum();

                let mut draw = rng.random_range(0..total);

                for (i, w) in weights.iter().enumerate() {

                    if draw < *w {

                        return i;

                    }

                    draw -= *w;

                }

                weights.len() - 1

            }

            Self::Clm { clm, .. } => clm.choose(&roll.state, roll.site, &roll.ask, options),

        }

    }

    /// A value in `lo..hi`. The rng arm draws uniformly; the clm arm picks from

    /// a 0.1-step grid so the model is choosing among described options.

    pub(crate) fn span(&mut self, roll: Roll, lo: f64, hi: f64) -> f64 {

        match self {

            Self::Rng(rng) => rng.random_range(lo..hi),

            Self::Clm { clm, .. } => {

                let mut last = format!("{lo:.1}");

                let mut values = Vec::new();

                let mut v = lo;

                while v < hi {

                    values.push(last);

                    v += 0.1;

                    last = format!("{v:.1}");

                }

                let options: Vec<&str> = values.iter().map(String::as_str).collect();

                let ask = format!("{}. Answer with a value.", roll.ask);

                let i = clm.choose(&roll.state, roll.site, &ask, &options);

                lo + 0.1 * i as f64

            }

        }

    }

    /// An integer in `lo..=hi`. The rng arm draws uniformly; the clm arm picks

    /// from the integers as described options.

    pub(crate) fn span_int(&mut self, roll: Roll, lo: i32, hi: i32) -> i32 {

        match self {

            Self::Rng(rng) => rng.random_range(lo..=hi),

            Self::Clm { clm, .. } => {

                let values: Vec<String> = (lo..=hi).map(|v| v.to_string()).collect();

                let options: Vec<&str> = values.iter().map(String::as_str).collect();

                let ask = format!("{}. Answer with a whole number.", roll.ask);

                let i = clm.choose(&roll.state, roll.site, &ask, &options);

                lo + i as i32

            }

        }

    }

}

impl Clm {

    fn new(url: &str) -> Self {

        Self {

            url: url.trim_end_matches('/').to_owned(),

            agent: ureq::AgentBuilder::new()

                .timeout(std::time::Duration::from_secs(60))

                .build(),

        }

    }

    /// POST /v1/systemone with a single question; panics on any failure, which

    /// surfaces as a 500 through the catch_panic layer. A dead oracle must not

    /// quietly fall back to the rng.

    fn ask(&self, state: &str, site: &str, question: Value) -> Value {

        let body = json!({

            "state": state,

            "model": "clm-latest",

            "questions": { site: question },

            "temperature": 1.0,

        });

        let response = self

            .agent

            .post(&self.url)

            .send_json(&body)

            .unwrap_or_else(|e| panic!("oracle unreachable at {}: {e}", self.url));

        let answer: Value = response

            .into_json()

            .unwrap_or_else(|e| panic!("oracle answer unreadable: {e}"));

        answer["answers"][site].clone()

    }

    fn decide(&self, state: &str, site: &str, ask: &str) -> f64 {

        self.ask(state, site, json!({ "type": "noul", "instructions": ask }))["noul"]

            .as_f64()

            .unwrap_or_else(|| panic!("oracle noul answer for {site} missing"))

    }

    fn choose(&self, state: &str, site: &str, ask: &str, options: &[&str]) -> usize {

        let criteria: serde_json::Map<String, Value> = options

            .iter()

            .enumerate()

            .map(|(i, text)| (i.to_string(), json!(text)))

            .collect();

        let q = if ask.trim_end().ends_with('?') {

            ""

        } else {

            "?"

        };

        let instructions = format!("{ask}{q}");

        let answer = self.ask(

            state,

            site,

            json!({ "type": "choice", "instructions": instructions, "criteria": criteria }),

        );

        let choice = answer["choice"]

            .as_str()

            .unwrap_or_else(|| panic!("oracle choice answer for {site} missing"));

        choice

            .parse::<usize>()

            .ok()

            .filter(|&i| i < options.len())

            .unwrap_or_else(|| panic!("oracle chose {choice:?} for {site}, not an option index"))

    }

}