token_optimizer/llm_envelope/
mod.rs

1// ================================================================================
2// PRODUCT  : sovereign-stack:token-optimizer
3// COMPONENT: LLM Envelope (Transport Protocol)
4// FILE     : crates/token-optimizer/src/llm_envelope/mod.rs
5// ROLE     : Handles the JSON-wrapped TOML payload for efficient IPC and APIs.
6// PURPOSE  : To bypass JavaScript object-mapping brittleness and optimize 
7//            token consumption in LLM context windows.
8// AUTHOR   : Chamara Somaratne assisted by Gemini, Ashby, Serge & Ciara 
9//            (Sovereign Gestalt)
10// LICENSE  : Apache-2.0
11// ================================================================================
12
13use serde::{Deserialize, Serialize};
14use std::collections::HashMap;
15
16// ==============================================================================
17// PHASE 1: TRAIT DEFINITIONS
18// ==============================================================================
19
20pub trait Envelopable: Serialize {
21    fn to_toml_payload(&self) -> Result<String, String> {
22        toml::to_string(self).map_err(|e| format!("TOML_SERIALIZATION_ERROR: {}", e))
23    }
24}
25
26// ==============================================================================
27// PHASE 2: THE SOVEREIGN ENVELOPE
28// ==============================================================================
29
30#[derive(Debug, Clone, Serialize, Deserialize)]
31pub struct Envelope {
32    pub persona: String,
33    pub metadata: HashMap<String, String>,
34    pub payload: String,
35}
36
37impl Envelope {
38    pub fn new(persona: &str, payload: String) -> Self {
39        Self {
40            persona: persona.to_string(),
41            metadata: HashMap::new(),
42            payload,
43        }
44    }
45
46    pub fn pack<T: Envelopable>(persona: &str, data: &T) -> Result<String, String> {
47        let toml_content = data.to_toml_payload()?;
48        let envelope = Self::new(persona, toml_content);
49        
50        serde_json::to_string(&envelope).map_err(|e| format!("IPC_PACKING_ERROR: {}", e))
51    }
52
53    pub fn unpack(json_input: &str) -> Result<Self, String> {
54        serde_json::from_str(json_input).map_err(|e| format!("IPC_UNPACKING_ERROR: {}", e))
55    }
56}
57
58// ==============================================================================
59// PHASE 3: ORACLE INTEGRATION
60// PURPOSE: Prepare the envelope content for the final Oracle request.
61// ==============================================================================
62
63impl Envelope {
64    // --------------------------------------------------------------------------------
65    // 3.1 Prompt Synthesis (to_oracle_prompt)
66    // PURPOSE: Formats the Envelope for the final Oracle request.
67    // --------------------------------------------------------------------------------
68    pub fn to_oracle_prompt(&self) -> String {
69        format!(
70            "--- START ENGRAM [{}] ---\n{}\n--- END ENGRAM ---",
71            self.persona.to_uppercase(),
72            self.payload
73        )
74    }
75   
76    // --------------------------------------------------------------------------------
77    // BRIDGE: JSON Object -> Sovereign Envelope (JSON with TOML payload)
78    // PURPOSE: Allows a frontend dev to pass a standard JSON string/object and 
79    //          get back a Sovereign-compliant Envelope with optimized TOML.
80    // --------------------------------------------------------------------------------
81    pub fn json_to_toml(persona: &str, json_input: &str) -> Result<Self, String> {
82        // 1. Parse the incoming JSON into a generic Value
83        let json_value: serde_json::Value = serde_json::from_str(json_input)
84            .map_err(|e| format!("INCOMING_JSON_INVALID: {}", e))?;
85
86        // 2. Convert that Value into a TOML string (Optimization step)
87        let toml_payload = toml::to_string(&json_value)
88            .map_err(|e| format!("TOML_CONVERSION_FAILED: {}", e))?;
89
90        // 3. Wrap it in the Envelope
91        Ok(Self::new(persona, toml_payload))
92    }
93
94    // --------------------------------------------------------------------------------
95    // BRIDGE: TOML Payload -> JSON String
96    // PURPOSE: When the Oracle returns a TOML-formatted response, this converts it
97    //          back to JSON so the Frontend/UI can easily render it.
98    // --------------------------------------------------------------------------------
99    pub fn toml_to_json(&self) -> Result<String, String> {
100        let toml_value: toml::Value = toml::from_str(&self.payload)
101            .map_err(|e| format!("ORACLE_TOML_INVALID: {}", e))?;
102
103        serde_json::to_string(&toml_value)
104            .map_err(|e| format!("JSON_RECONSTRUCTION_FAILED: {}", e))?
105            .to_string()
106            .pipe_ok() // or just wrap in Ok()
107    }
108}
109
110// Helper for the pipe (optional, but clean)
111trait PipeOk { fn pipe_ok(self) -> Result<Self, String> where Self: Sized; }
112impl PipeOk for String { fn pipe_ok(self) -> Result<Self, String> { Ok(self) } }
token_optimizer/llm_envelope/mod.rs

token_optimizer/llm_envelope/
mod.rs
