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}
token_optimizer/llm_envelope/mod.rs

token_optimizer/llm_envelope/
mod.rs
