token-optimizer 0.1.4

// ================================================================================
// PRODUCT  : sovereign-stack:token-optimizer
// COMPONENT: LLM Envelope (Transport Protocol)
// FILE     : crates/token-optimizer/src/llm_envelope/mod.rs
// ROLE     : Handles the JSON-wrapped TOML payload for efficient IPC and APIs.
// PURPOSE  : To bypass JavaScript object-mapping brittleness and optimize 
//            token consumption in LLM context windows.
// AUTHOR   : Chamara Somaratne assisted by Gemini, Ashby, Serge & Ciara 
//            (Sovereign Gestalt)
// LICENSE  : Apache-2.0
// ================================================================================

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

// ==============================================================================
// PHASE 1: TRAIT DEFINITIONS
// ==============================================================================

pub trait Envelopable: Serialize {
    fn to_toml_payload(&self) -> Result<String, String> {
        toml::to_string(self).map_err(|e| format!("TOML_SERIALIZATION_ERROR: {}", e))
    }
}

// ==============================================================================
// PHASE 2: THE SOVEREIGN ENVELOPE
// ==============================================================================

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Envelope {
    pub persona: String,
    pub metadata: HashMap<String, String>,
    pub payload: String,
}

impl Envelope {
    pub fn new(persona: &str, payload: String) -> Self {
        Self {
            persona: persona.to_string(),
            metadata: HashMap::new(),
            payload,
        }
    }

    pub fn pack<T: Envelopable>(persona: &str, data: &T) -> Result<String, String> {
        let toml_content = data.to_toml_payload()?;
        let envelope = Self::new(persona, toml_content);
        
        serde_json::to_string(&envelope).map_err(|e| format!("IPC_PACKING_ERROR: {}", e))
    }

    pub fn unpack(json_input: &str) -> Result<Self, String> {
        serde_json::from_str(json_input).map_err(|e| format!("IPC_UNPACKING_ERROR: {}", e))
    }
}

// ==============================================================================
// PHASE 3: ORACLE INTEGRATION
// PURPOSE: Prepare the envelope content for the final Oracle request.
// ==============================================================================

impl Envelope {
    // --------------------------------------------------------------------------------
    // 3.1 Prompt Synthesis (to_oracle_prompt)
    // PURPOSE: Formats the Envelope for the final Oracle request.
    // --------------------------------------------------------------------------------
    pub fn to_oracle_prompt(&self) -> String {
        format!(
            "--- START ENGRAM [{}] ---\n{}\n--- END ENGRAM ---",
            self.persona.to_uppercase(),
            self.payload
        )
    }
   
    // --------------------------------------------------------------------------------
    // BRIDGE: JSON Object -> Sovereign Envelope (JSON with TOML payload)
    // PURPOSE: Allows a frontend dev to pass a standard JSON string/object and 
    //          get back a Sovereign-compliant Envelope with optimized TOML.
    // --------------------------------------------------------------------------------
    pub fn json_to_toml(persona: &str, json_input: &str) -> Result<Self, String> {
        // 1. Parse the incoming JSON into a generic Value
        let json_value: serde_json::Value = serde_json::from_str(json_input)
            .map_err(|e| format!("INCOMING_JSON_INVALID: {}", e))?;

        // 2. Convert that Value into a TOML string (Optimization step)
        let toml_payload = toml::to_string(&json_value)
            .map_err(|e| format!("TOML_CONVERSION_FAILED: {}", e))?;

        // 3. Wrap it in the Envelope
        Ok(Self::new(persona, toml_payload))
    }

    // --------------------------------------------------------------------------------
    // BRIDGE: TOML Payload -> JSON String
    // PURPOSE: When the Oracle returns a TOML-formatted response, this converts it
    //          back to JSON so the Frontend/UI can easily render it.
    // --------------------------------------------------------------------------------
    pub fn toml_to_json(&self) -> Result<String, String> {
        let toml_value: toml::Value = toml::from_str(&self.payload)
            .map_err(|e| format!("ORACLE_TOML_INVALID: {}", e))?;

        serde_json::to_string(&toml_value)
            .map_err(|e| format!("JSON_RECONSTRUCTION_FAILED: {}", e))?
            .to_string()
            .pipe_ok() // or just wrap in Ok()
    }
}

// Helper for the pipe (optional, but clean)
trait PipeOk { fn pipe_ok(self) -> Result<Self, String> where Self: Sized; }
impl PipeOk for String { fn pipe_ok(self) -> Result<Self, String> { Ok(self) } }