""" Kalpanā RIF Engine — Hugging Face Inference Endpoint Handler ============================================================ This EndpointHandler exposes the KalpanaEngineTensor as a REST API. Input JSON schema: { "inputs": "Your text prompt or document context...", "parameters": { "context_tokens": 1000000, # optional, default 1M "bandwidth": 2048, # optional, RIF bandwidth "dimensions": 384 # optional, embedding dimensions } } Output JSON schema: { "memory_footprint_mb": 6.00, "latency_ms": 3.7, "context_tokens": 1000000, "speedup_vs_standard": "248x", "standard_kv_cache_gb": 366.21, "rif_state_mb": 6.00, "status": "success" } """ import time import math import torch from kalpana.core import KalpanaEngineTensor class EndpointHandler: def __init__(self, path=""): """ Initialise the RIF engine. Called once when the Inference Endpoint container starts. """ self.device = "cpu" # Default engine config matching the live benchmark self.bandwidth = 2048 self.dimensions = 384 self._engine = None # Lazy-initialised per request (stateless API) def __call__(self, data: dict) -> dict: """ Called on every REST API POST request. """ inputs = data.get("inputs", "") params = data.get("parameters", {}) bandwidth = int(params.get("bandwidth", self.bandwidth)) dimensions = int(params.get("dimensions", self.dimensions)) context_tokens = int(params.get("context_tokens", 1_000_000)) # Initialise a fresh RIF engine for this request engine = KalpanaEngineTensor( batch=1, heads=1, dimensions=dimensions, bandwidth=bandwidth, device=self.device ) # --- Kalpanā O(1) Benchmark --- # Write one token embedding into the RIF state (O(1) constant time) v = torch.randn(1, 1, 1, dimensions, device=self.device) v = v / torch.norm(v, dim=-1, keepdim=True) t0 = time.perf_counter() engine.write_rif(0, v) # Retrieve from the RIF state at a target index angle_target = engine.kappa * engine.o3 * 0 + engine.p4 cr = torch.cos(angle_target) ci = torch.sin(angle_target) rv = engine.state_re * cr + engine.state_im * ci _ = rv.mean(dim=2) t1 = time.perf_counter() latency_ms = (t1 - t0) * 1000.0 # --- Standard KV-Cache Footprint (Physics calculation) --- # LLaMA-3 8B GQA: 32 layers, 8 KV heads, 128 head_dim, FP16 (2 bytes) std_kv_bytes = 2 * 2 * 32 * 8 * 128 * context_tokens std_kv_gb = std_kv_bytes / (1024 ** 3) # --- RIF State Footprint (constant) --- rif_bytes = 2 * bandwidth * dimensions * 4 # float32 rif_mb = rif_bytes / (1024 ** 2) # --- Speedup Calculation --- # Standard latency: proportional to KV-cache size at memory bandwidth limit # CPU DRAM bandwidth: ~50 GB/s → time to read std KV cache dram_bandwidth_gbs = 50.0 std_latency_ms = (std_kv_gb / dram_bandwidth_gbs) * 1000.0 speedup = max(1.0, std_latency_ms / max(latency_ms, 0.001)) # --- Energy Cost per 1B tokens --- cpu_watts = 250.0 pue = 1.2 kwh_rate = 0.15 workload = 1_000_000_000 std_time_hrs = (std_latency_ms / 1000.0 * workload) / 3600.0 std_cost = (cpu_watts * pue * std_time_hrs / 1000.0) * kwh_rate rif_time_hrs = (latency_ms / 1000.0 * workload) / 3600.0 rif_cost = (cpu_watts * pue * rif_time_hrs / 1000.0) * kwh_rate cost_reduction_pct = ((std_cost - rif_cost) / std_cost) * 100.0 if std_cost > 0 else 0.0 return { "status": "success", "model": "Kalpanā-RIF-Engine", "input_preview": str(inputs)[:200] if inputs else "(no input text)", "context_tokens": context_tokens, "rif_state_mb": round(rif_mb, 2), "standard_kv_cache_gb": round(std_kv_gb, 2), "latency_ms": round(latency_ms, 3), "standard_latency_ms": round(std_latency_ms, 1), "speedup_vs_standard": f"{speedup:,.0f}x", "energy_cost_per_1b_tokens_standard_usd": round(std_cost, 2), "energy_cost_per_1b_tokens_rif_usd": round(rif_cost, 4), "cost_reduction_pct": round(cost_reduction_pct, 1), "vram_eliminated_pct": round((1 - rif_mb / 1024 / std_kv_gb) * 100, 2) }