src/sdk.rs

// 🌌 [BioPhys 6.0 공식 Rust SDK: biophys_engine::sdk] (src/sdk.rs)
// 외부 애플리케이션(Tauri, Axum, CLI, Python FFI)에서 1줄 코드로 16GB 지평선 AI를 구동하는 개발자 키트

use std::time::Instant;
use crate::applied_rust2026_features::StreamingTokenIterator;
use crate::dynamic_knowledge_rag::{DynamicKnowledgeRAG, DynamicDocument};
use crate::dynamic_phase_interpreter::{DynamicScriptParser, PhaseVM};
use crate::ecosystem_evolution::{MutationInjector, SubconsciousMixer, SporeArchiver};
use crate::generative_llm::{GenerativeEngine, GenerativeContext};
use crate::native_bpe_tokenizer::NativeBpeTokenizer;
use crate::parallel_engine::LargeScaleEngine;
use crate::solar_moe_router::SolarMoERouter;
use crate::tachyon_speculative::TachyonSpeculativeEngine;
use crate::token_autoregressive_snn::SpikingTokenEngine;

/// ⚙️ [SDK 구성 설정 (Builder Pattern)]
#[derive(Debug, Clone)]
pub struct BioPhysConfig {
    pub lattice_size: usize,        // 물리 격자 크기 (기본 256x256)
    pub temperature: f32,           // 생성 다양성 온도 (0.0 ~ 1.0)
    pub mutation_rate: f32,         // 우주 방사선 돌연변이율
    pub subconscious_bleed: f32,    // 세션 간 무의식 누수율 (기본 0.03 = 3%)
    pub top_k_retrieval: usize,     // RAG 인출 문서 수
    pub lookahead_speculative: usize, // 타키온 투기적 디코딩 미래 토큰 수
}

impl Default for BioPhysConfig {
    fn default() -> Self {
        BioPhysConfig {
            lattice_size: 256,
            temperature: 0.3,
            mutation_rate: 0.002,
            subconscious_bleed: 0.03,
            top_k_retrieval: 2,
            lookahead_speculative: 4,
        }
    }
}

/// 📦 [SDK 서술형 응답 결과 객체]
#[derive(Debug, Clone)]
pub struct BioPhysResponse {
    pub text: String,               // 생성된 텍스트
    pub latency_ms: f64,            // 총 처리 지연 시간 (ms)
    pub routed_planet: String,      // 할당된 태양계 6행성 MoE 뇌 이름
    pub planet_orbit_au: f32,       // 궤도 반경 (AU)
    pub energy_level: f32,          // 물리 격자 계면 에너지
    pub is_verified: bool,          // 조석 고정 쌍성 환각 차단 통과 여부
    pub resonance_score: f32,       // 지평선 공명 일치도
    pub retrieved_docs_count: usize,// 참조된 RAG 지식 건수
}

/// 📊 [SDK 실시간 텔레메트리 상태]
#[derive(Debug, Clone)]
pub struct BioPhysTelemetry {
    pub active_nodes: usize,        // 격자 활성 노드 수 (65,536)
    pub avg_energy: f32,            // 평균 계면 에너지
    pub total_queries_served: usize,// 누적 처리 질의 수
    pub mutations_applied: usize,   // 누적 돌연변이 진화 횟수
    pub subconscious_sessions: usize,// 누적 무의식 세션 수
}

/// 🚀 [BioPhys 6.0 공식 클라이언트 (Main SDK Entrypoint)]
pub struct BioPhysClient {
    pub config: BioPhysConfig,
    engine: LargeScaleEngine,
    rag: DynamicKnowledgeRAG,
    solar_router: SolarMoERouter,
    mutator: MutationInjector,
    subconscious_mixer: SubconsciousMixer,
    spore_archiver: SporeArchiver,
    tokenizer: NativeBpeTokenizer,
    tachyon_engine: TachyonSpeculativeEngine,
    spiking_token_engine: SpikingTokenEngine,
    vm: PhaseVM,
    total_queries: usize,
}

impl BioPhysClient {
    /// 1. 기본 설정으로 SDK 클라이언트 초기화 (1줄 시작)
    pub fn new() -> Self {
        Self::with_config(BioPhysConfig::default())
    }

    /// 2. 커스텀 설정을 적용하여 SDK 클라이언트 초기화
    pub fn with_config(config: BioPhysConfig) -> Self {
        let engine = LargeScaleEngine::new(config.lattice_size);
        let rag = DynamicKnowledgeRAG::new("knowledge_corpus");
        let solar_router = SolarMoERouter::new();
        let mutator = MutationInjector::new(config.mutation_rate);
        let subconscious_mixer = SubconsciousMixer::new(config.lattice_size, config.subconscious_bleed);
        let spore_archiver = SporeArchiver::new();
        let tokenizer = NativeBpeTokenizer::new();
        let tachyon_engine = TachyonSpeculativeEngine::new(config.lattice_size, config.lookahead_speculative);
        let spiking_token_engine = SpikingTokenEngine::new(config.lattice_size);
        let vm = PhaseVM::new();

        BioPhysClient {
            config,
            engine,
            rag,
            solar_router,
            mutator,
            subconscious_mixer,
            spore_archiver,
            tokenizer,
            tachyon_engine,
            spiking_token_engine,
            vm,
            total_queries: 0,
        }
    }

    /// 3. [동기식 완성형 질의응답 (Generate API)]
    /// 질문을 받아 태양계 라우팅, RAG 인출, 무의식 혼합, 쌍성 환각 검증을 거친 최종 응답 반환
    pub fn generate(&mut self, prompt: &str) -> BioPhysResponse {
        let start_time = Instant::now();
        self.total_queries += 1;

        // 1. 태양계 MoE 동적 라우팅
        let target_planet = self.solar_router.route_query(prompt);
        let planet_name = target_planet.name.clone();
        let planet_au = target_planet.orbit_au;

        // 2. 물리 격자 동역학 연산 & 무의식 누수 믹싱
        let avg_e = self.engine.step_parallel();
        let mut latent = vec![avg_e; self.config.lattice_size];
        self.subconscious_mixer.blend_subconscious(&mut latent);

        // 3. 우주 방사선 돌연변이 시험
        let mut weights_sample = vec![0x55555555; 50];
        self.mutator.inject_cosmic_mutation(&mut weights_sample, avg_e, |_| 0.521);

        // 4. 블랙홀 지평선 RAG 인출
        let search_results = self.rag.search_documents(prompt, self.config.top_k_retrieval);
        let retrieved_docs: Vec<DynamicDocument> = search_results.into_iter().map(|(d, _)| d.clone()).collect();
        let docs_count = retrieved_docs.len();

        // 5. 지평선 생성 및 조석 고정 쌍성 환각 검증
        let mode = GenerativeEngine::detect_mode(prompt);
        let ctx = GenerativeContext {
            prompt: prompt.to_string(),
            retrieved_docs,
            temperature: self.config.temperature,
            mode,
        };
        let response_text = GenerativeEngine::generate_response(&ctx, avg_e);
        let (is_verified, resonance) = self.solar_router.verify_binary_singularity(&response_text, "BioPhys 2-Bit 지평선 물리");

        let latency_ms = start_time.elapsed().as_secs_f64() * 1000.0;

        BioPhysResponse {
            text: response_text,
            latency_ms,
            routed_planet: planet_name,
            planet_orbit_au: planet_au,
            energy_level: avg_e,
            is_verified,
            resonance_score: resonance,
            retrieved_docs_count: docs_count,
        }
    }

    /// 4. [실시간 토큰 스트리밍 (Streaming API)]
    /// 토큰이 생성되는 순간 1개씩 즉시 방출하는 Zero-Allocation 스트림 반복자 생성
    pub fn stream_tokens<'a>(&'a mut self, max_tokens: usize) -> StreamingTokenIterator<'a> {
        StreamingTokenIterator::new(&self.spiking_token_engine.vocab, max_tokens, 0)
    }

    /// 5. [동적 바이트코드 스크립트 실행 (Interpreter API)]
    /// 인공지능이 생성한 임의의 텍스트 스크립트를 샌드박스 VM에서 즉석 해석 실행
    pub fn execute_script(&mut self, script: &str) -> Result<Option<f32>, String> {
        let bytecodes = DynamicScriptParser::compile_script(script);
        self.vm.load_program(bytecodes);
        self.vm.run()
    }

    /// 6. [실시간 텔레메트리 조회 (Telemetry API)]
    pub fn get_telemetry(&mut self) -> BioPhysTelemetry {
        let avg_e = self.engine.step_parallel();
        BioPhysTelemetry {
            active_nodes: self.config.lattice_size * self.config.lattice_size,
            avg_energy: avg_e,
            total_queries_served: self.total_queries,
            mutations_applied: self.mutator.total_mutations_applied,
            subconscious_sessions: self.subconscious_mixer.session_count,
        }
    }
}