algocline_core/

query.rs

use serde::{Deserialize, Serialize};
use std::fmt;

/// Query identifier within a batch.
///
/// Use `single()` for alc.llm(), `batch(index)` for alc.llm_batch().
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct QueryId(String);

impl QueryId {
    /// For single alc.llm() calls.
    pub fn single() -> Self {
        Self("q-0".into())
    }

    /// For alc.llm_batch() with the given index.
    pub fn batch(index: usize) -> Self {
        Self(format!("q-{index}"))
    }

    /// For alc.fork() — identifies queries by child VM index and sequence.
    pub fn fork(vm_index: usize, seq: usize) -> Self {
        Self(format!("f-{vm_index}-{seq}"))
    }

    /// Construct from an arbitrary string (e.g. MCP parameters).
    pub fn parse(s: &str) -> Self {
        Self(s.to_string())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl fmt::Display for QueryId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

/// LLM request emitted during execution.
/// Transport-agnostic (no channel, HTTP, or MCP Sampling details).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LlmQuery {
    pub id: QueryId,
    pub prompt: String,
    pub system: Option<String>,
    pub max_tokens: u32,
    /// When true, the host should ground the response in external evidence
    /// (web search, code reading, documentation, etc.) rather than relying
    /// solely on LLM internal knowledge. The host decides the means.
    #[serde(default, skip_serializing_if = "is_false")]
    pub grounded: bool,
    /// When true, the prompt's preconditions depend on intent/goal definitions
    /// that exist outside the current context and cannot be inferred by the LLM.
    /// The host decides the resolution means (user query, RAG, DB lookup,
    /// delegated agent, etc.).
    #[serde(default, skip_serializing_if = "is_false")]
    pub underspecified: bool,
    /// Optional opaque hint to the host on where to place a prompt-cache
    /// boundary (e.g. Anthropic `cache_control` block). The engine does not
    /// interpret the value — it forwards it verbatim on the paused-session
    /// JSON so the host can map it to the provider-specific cache API.
    ///
    /// Recommended values (host-defined; engine is opaque):
    /// - `"context"` — cache everything up to and including the system prompt
    ///   / long shared context so that repeated calls (panel / moa / ucb) hit
    ///   the cache
    /// - `"prompt"` — cache the full prompt including user turn
    ///
    /// Absent when not set; hosts that do not implement prompt caching MUST
    /// ignore the field.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_breakpoint: Option<String>,
    /// Optional role hint identifying the caller context of this query.
    ///
    /// Set to `"grader"` by the LLM-as-Judge grader wiring (see
    /// `alc.eval`) so the host can distinguish a judge/grading call from
    /// the default strategy call and route it to a different model (named
    /// model role + default fallback). The engine does not interpret the
    /// value — it forwards it verbatim on the paused-session JSON.
    ///
    /// Absent when not set; hosts that do not implement role-based routing
    /// MUST ignore the field.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub role: Option<String>,
}

fn is_false(v: &bool) -> bool {
    !v
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn single_query_id() {
        let id = QueryId::single();
        assert_eq!(id.as_str(), "q-0");
        assert_eq!(id.to_string(), "q-0");
    }

    #[test]
    fn batch_query_ids_are_unique() {
        let ids: Vec<QueryId> = (0..5).map(QueryId::batch).collect();
        let set: std::collections::HashSet<&QueryId> = ids.iter().collect();
        assert_eq!(set.len(), 5);
        assert_eq!(ids[0].as_str(), "q-0");
        assert_eq!(ids[3].as_str(), "q-3");
    }

    #[test]
    fn single_equals_batch_zero() {
        assert_eq!(QueryId::single(), QueryId::batch(0));
    }

    #[test]
    fn parse_roundtrip() {
        let id = QueryId::parse("q-42");
        assert_eq!(id.as_str(), "q-42");
        assert_eq!(id, QueryId::batch(42));
    }

    #[test]
    fn parse_arbitrary() {
        let id = QueryId::parse("custom-id");
        assert_eq!(id.as_str(), "custom-id");
    }

    #[test]
    fn fork_query_id() {
        let id = QueryId::fork(2, 3);
        assert_eq!(id.as_str(), "f-2-3");
    }

    #[test]
    fn fork_query_ids_are_unique() {
        let ids: Vec<QueryId> = (0..3)
            .flat_map(|vm| (0..2).map(move |seq| QueryId::fork(vm, seq)))
            .collect();
        let set: std::collections::HashSet<&QueryId> = ids.iter().collect();
        assert_eq!(set.len(), 6);
    }

    #[test]
    fn query_id_roundtrip_json() {
        let id = QueryId::batch(42);
        let json = serde_json::to_string(&id).unwrap();
        let restored: QueryId = serde_json::from_str(&json).unwrap();
        assert_eq!(id, restored);
    }

    #[test]
    fn llm_query_roundtrip_json() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "test prompt".into(),
            system: Some("system".into()),
            max_tokens: 1024,
            grounded: false,
            underspecified: false,
            cache_breakpoint: None,
            role: None,
        };
        let json = serde_json::to_value(&query).unwrap();
        assert!(
            json.get("grounded").is_none(),
            "grounded key must be absent when false (skip_serializing_if)"
        );
        assert!(
            json.get("underspecified").is_none(),
            "underspecified key must be absent when false (skip_serializing_if)"
        );
        assert!(
            json.get("cache_breakpoint").is_none(),
            "cache_breakpoint key must be absent when None (skip_serializing_if)"
        );
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert_eq!(restored.id, query.id);
        assert_eq!(restored.prompt, query.prompt);
        assert_eq!(restored.system, query.system);
        assert_eq!(restored.max_tokens, query.max_tokens);
        assert!(!restored.grounded);
        assert!(!restored.underspecified);
        assert!(restored.cache_breakpoint.is_none());
    }

    #[test]
    fn llm_query_grounded_serde() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "verify this".into(),
            system: None,
            max_tokens: 200,
            grounded: true,
            underspecified: false,
            cache_breakpoint: None,
            role: None,
        };
        let json = serde_json::to_value(&query).unwrap();
        assert_eq!(
            json["grounded"], true,
            "grounded key must be present when true"
        );
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert!(restored.grounded);
    }

    #[test]
    fn llm_query_grounded_default_on_missing_key() {
        let json = serde_json::json!({
            "id": "q-single",
            "prompt": "test",
            "system": null,
            "max_tokens": 100
        });
        let query: LlmQuery = serde_json::from_value(json).unwrap();
        assert!(
            !query.grounded,
            "grounded must default to false when key absent"
        );
        assert!(
            !query.underspecified,
            "underspecified must default to false when key absent"
        );
        assert!(
            query.cache_breakpoint.is_none(),
            "cache_breakpoint must default to None when key absent"
        );
    }

    #[test]
    fn llm_query_underspecified_serde() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "what format do you want?".into(),
            system: None,
            max_tokens: 200,
            grounded: false,
            underspecified: true,
            cache_breakpoint: None,
            role: None,
        };
        let json = serde_json::to_value(&query).unwrap();
        assert_eq!(
            json["underspecified"], true,
            "underspecified key must be present when true"
        );
        assert!(
            json.get("grounded").is_none(),
            "grounded must be absent when false"
        );
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert!(restored.underspecified);
        assert!(!restored.grounded);
    }

    #[test]
    fn llm_query_both_flags_serde() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "clarify and verify".into(),
            system: None,
            max_tokens: 300,
            grounded: true,
            underspecified: true,
            cache_breakpoint: None,
            role: None,
        };
        let json = serde_json::to_value(&query).unwrap();
        assert_eq!(json["grounded"], true);
        assert_eq!(json["underspecified"], true);
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert!(restored.grounded);
        assert!(restored.underspecified);
    }

    #[test]
    fn llm_query_cache_breakpoint_serde() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "cached prompt".into(),
            system: Some("shared system".into()),
            max_tokens: 512,
            grounded: false,
            underspecified: false,
            cache_breakpoint: Some("context".into()),
            role: None,
        };
        let json = serde_json::to_value(&query).unwrap();
        assert_eq!(
            json["cache_breakpoint"], "context",
            "cache_breakpoint must be forwarded verbatim when set"
        );
        assert!(
            json.get("grounded").is_none(),
            "grounded must be absent when false"
        );
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert_eq!(restored.cache_breakpoint.as_deref(), Some("context"));
    }

    #[test]
    fn llm_query_role_serde() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "grade this".into(),
            system: None,
            max_tokens: 256,
            grounded: false,
            underspecified: false,
            cache_breakpoint: None,
            role: Some("grader".into()),
        };
        let json = serde_json::to_value(&query).unwrap();
        assert_eq!(
            json["role"], "grader",
            "role must be forwarded verbatim when set"
        );
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert_eq!(restored.role.as_deref(), Some("grader"));
    }

    #[test]
    fn llm_query_role_absent_when_none() {
        let query = LlmQuery {
            id: QueryId::single(),
            prompt: "no role".into(),
            system: None,
            max_tokens: 128,
            grounded: false,
            underspecified: false,
            cache_breakpoint: None,
            role: None,
        };
        let json = serde_json::to_value(&query).unwrap();
        assert!(
            json.get("role").is_none(),
            "role key must be absent when None (skip_serializing_if)"
        );
        let restored: LlmQuery = serde_json::from_value(json).unwrap();
        assert!(restored.role.is_none());
    }
}

#[cfg(test)]
mod proptests {
    use super::*;
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn parse_roundtrip_arbitrary(s in "\\PC{1,100}") {
            let id = QueryId::parse(&s);
            prop_assert_eq!(id.as_str(), s.as_str());
        }

        #[test]
        fn batch_roundtrip(index in 0usize..10_000) {
            let id = QueryId::batch(index);
            let expected = format!("q-{index}");
            prop_assert_eq!(id.as_str(), expected.as_str());
        }

        #[test]
        fn display_matches_as_str(s in "\\PC{1,100}") {
            let id = QueryId::parse(&s);
            prop_assert_eq!(id.to_string(), id.as_str().to_string());
        }

        #[test]
        fn serde_roundtrip_arbitrary(s in "\\PC{1,100}") {
            let id = QueryId::parse(&s);
            let json = serde_json::to_string(&id).unwrap();
            let restored: QueryId = serde_json::from_str(&json).unwrap();
            prop_assert_eq!(id, restored);
        }
    }
}