emergent-translator 1.1.0__py3-none-any.whl

emergent_translator/client_sdk.py

@@ -0,0 +1,903 @@
+# eudaimonia/translator/client_sdk.py
+
+"""
+Emergent Language Translator Client SDK
+
+Python and JavaScript SDKs for easy integration with the Emergent Language
+Translator API. Provides simple, high-level interfaces for external AI systems
+to compress their data using Eudaimonia's native θ symbol format.
+
+Features:
+- Simple async/sync Python client
+- Batch translation support
+- WebSocket streaming
+- Automatic retries and error handling
+- Compression statistics
+- TypeScript definitions for JavaScript
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import Dict, List, Optional, Union, Any, AsyncGenerator, Tuple
+from dataclasses import dataclass
+import base64
+
+import httpx
+import websockets
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TranslationConfig:
+    """Configuration for translator client."""
+    api_base_url: str = "http://localhost:8000"
+    auth_token: Optional[str] = None
+    timeout: float = 30.0
+    max_retries: int = 3
+    retry_delay: float = 1.0
+
+
+@dataclass
+class ClientTranslationResult:
+    """Client-side translation result."""
+    success: bool
+    translated_data: Optional[bytes] = None
+    original_size: int = 0
+    translated_size: int = 0
+    compression_ratio: float = 0.0
+    efficiency_gain: float = 0.0
+    translation_time_ms: float = 0.0
+    symbol_count: int = 0
+    symbol_families: List[str] = None
+    metadata: Dict[str, Any] = None
+    errors: List[str] = None
+
+    def __post_init__(self):
+        if self.symbol_families is None:
+            self.symbol_families = []
+        if self.metadata is None:
+            self.metadata = {}
+        if self.errors is None:
+            self.errors = []
+
+
+class EmergentTranslatorClient:
+    """
+    Async client for Emergent Language Translator API.
+
+    Provides high-level interface for translating data to Eudaimonia's
+    emergent language format with automatic retries and error handling.
+
+    Example:
+        async with EmergentTranslatorClient() as client:
+            result = await client.translate_json({"task": "analyze data"})
+            print(f"Compression: {result.efficiency_gain:.1f}%")
+    """
+
+    def __init__(self, config: Optional[TranslationConfig] = None):
+        """Initialize client with configuration."""
+        self.config = config or TranslationConfig()
+        self._client: Optional[httpx.AsyncClient] = None
+        self._websocket: Optional[websockets.WebSocketServerProtocol] = None
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self._ensure_client()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+    async def _ensure_client(self):
+        """Ensure HTTP client is initialized."""
+        if self._client is None:
+            headers = {}
+            if self.config.auth_token:
+                headers["Authorization"] = f"Bearer {self.config.auth_token}"
+
+            self._client = httpx.AsyncClient(
+                base_url=self.config.api_base_url,
+                headers=headers,
+                timeout=self.config.timeout
+            )
+
+    async def close(self):
+        """Close client connections."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+        if self._websocket:
+            await self._websocket.close()
+            self._websocket = None
+
+    # Core translation methods
+
+    async def translate_json(
+        self,
+        data: Union[dict, str],
+        intent_type: str = "general",
+        epoch: int = 0,
+        enable_validation: bool = True
+    ) -> ClientTranslationResult:
+        """
+        Translate JSON data to emergent language symbols.
+
+        Args:
+            data: JSON data (dict or string)
+            intent_type: Intent type for better symbol selection
+            epoch: Emergent language epoch version
+            enable_validation: Enable symbol validation
+
+        Returns:
+            Translation result with compressed data and statistics
+        """
+        await self._ensure_client()
+
+        request_data = {
+            "data": data,
+            "source_format": "json",
+            "target_format": "emergent",
+            "intent_type": intent_type,
+            "epoch": epoch,
+            "enable_validation": enable_validation
+        }
+
+        return await self._make_translation_request(request_data)
+
+    async def translate_text(
+        self,
+        text: str,
+        intent_type: str = "general",
+        epoch: int = 0,
+        enable_validation: bool = True
+    ) -> ClientTranslationResult:
+        """
+        Translate natural language text to emergent symbols.
+
+        Args:
+            text: Natural language text
+            intent_type: Intent type (general, work, governance, social, resource)
+            epoch: Emergent language epoch version
+            enable_validation: Enable symbol validation
+
+        Returns:
+            Translation result with compressed data and statistics
+        """
+        await self._ensure_client()
+
+        request_data = {
+            "data": text,
+            "source_format": "text",
+            "target_format": "emergent",
+            "intent_type": intent_type,
+            "epoch": epoch,
+            "enable_validation": enable_validation
+        }
+
+        return await self._make_translation_request(request_data)
+
+    async def translate_from_emergent(
+        self,
+        symbol_data: bytes,
+        target_format: str = "json",
+        epoch: int = 0
+    ) -> ClientTranslationResult:
+        """
+        Translate emergent language symbols back to readable format.
+
+        Args:
+            symbol_data: Emergent language symbol bytes
+            target_format: Target format (json, text, etc.)
+            epoch: Emergent language epoch version
+
+        Returns:
+            Translation result with decompressed data
+        """
+        await self._ensure_client()
+
+        # Encode binary data as base64 for JSON transport
+        encoded_data = base64.b64encode(symbol_data).decode('utf-8')
+
+        request_data = {
+            "data": encoded_data,
+            "source_format": "binary",
+            "target_format": target_format,
+            "epoch": epoch
+        }
+
+        return await self._make_translation_request(request_data)
+
+    async def translate_batch(
+        self,
+        requests: List[Dict[str, Any]],
+        parallel: bool = True
+    ) -> List[ClientTranslationResult]:
+        """
+        Translate multiple data items in batch.
+
+        Args:
+            requests: List of translation request dictionaries
+            parallel: Process requests in parallel
+
+        Returns:
+            List of translation results
+        """
+        await self._ensure_client()
+
+        request_data = {
+            "requests": requests,
+            "parallel": parallel
+        }
+
+        try:
+            response = await self._client.post("/translate/batch", json=request_data)
+            response.raise_for_status()
+
+            result_data = response.json()
+
+            results = []
+            for result in result_data.get("results", []):
+                translated_data = None
+                if result.get("translated_data"):
+                    try:
+                        translated_data = base64.b64decode(result["translated_data"])
+                    except:
+                        translated_data = result["translated_data"].encode('utf-8')
+
+                results.append(ClientTranslationResult(
+                    success=result.get("success", False),
+                    translated_data=translated_data,
+                    original_size=result.get("original_size", 0),
+                    translated_size=result.get("translated_size", 0),
+                    compression_ratio=result.get("compression_ratio", 0.0),
+                    efficiency_gain=result.get("efficiency_gain", 0.0),
+                    translation_time_ms=result.get("translation_time_ms", 0.0),
+                    symbol_count=result.get("symbol_count", 0),
+                    symbol_families=result.get("symbol_families", []),
+                    metadata=result.get("metadata", {}),
+                    errors=result.get("errors", [])
+                ))
+
+            return results
+
+        except httpx.HTTPError as e:
+            logger.error(f"Batch translation HTTP error: {e}")
+            return [ClientTranslationResult(success=False, errors=[str(e)])]
+        except Exception as e:
+            logger.error(f"Batch translation error: {e}")
+            return [ClientTranslationResult(success=False, errors=[str(e)])]
+
+    # WebSocket streaming interface
+
+    async def stream_translations(
+        self
+    ) -> AsyncGenerator[ClientTranslationResult, None]:
+        """
+        Open WebSocket connection for streaming translations.
+
+        Yields:
+            Translation results as they are processed
+        """
+        ws_url = self.config.api_base_url.replace("http://", "ws://").replace("https://", "wss://")
+        ws_url += "/ws/translate"
+
+        try:
+            async with websockets.connect(ws_url) as websocket:
+                self._websocket = websocket
+
+                while True:
+                    try:
+                        # Wait for incoming message
+                        message = await websocket.recv()
+                        result_data = json.loads(message)
+
+                        # Convert to client result
+                        translated_data = None
+                        if result_data.get("translated_data"):
+                            try:
+                                translated_data = base64.b64decode(result_data["translated_data"])
+                            except:
+                                pass
+
+                        result = ClientTranslationResult(
+                            success=result_data.get("success", False),
+                            translated_data=translated_data,
+                            symbol_families=result_data.get("symbol_families", []),
+                            errors=result_data.get("errors", [])
+                        )
+
+                        # Add stats if available
+                        if "stats" in result_data:
+                            stats = result_data["stats"]
+                            result.original_size = stats.get("original_size", 0)
+                            result.translated_size = stats.get("translated_size", 0)
+                            result.compression_ratio = stats.get("compression_ratio", 0.0)
+                            result.efficiency_gain = stats.get("efficiency_gain", 0.0)
+                            result.symbol_count = stats.get("symbol_count", 0)
+
+                        yield result
+
+                    except websockets.exceptions.ConnectionClosed:
+                        break
+                    except json.JSONDecodeError as e:
+                        yield ClientTranslationResult(success=False, errors=[f"JSON decode error: {e}"])
+                    except Exception as e:
+                        yield ClientTranslationResult(success=False, errors=[str(e)])
+
+        except Exception as e:
+            logger.error(f"WebSocket connection error: {e}")
+            yield ClientTranslationResult(success=False, errors=[str(e)])
+
+    async def send_streaming_request(self, request_data: Dict[str, Any]):
+        """
+        Send translation request via WebSocket.
+
+        Args:
+            request_data: Translation request data
+        """
+        if self._websocket:
+            await self._websocket.send(json.dumps(request_data))
+        else:
+            raise RuntimeError("WebSocket not connected. Use stream_translations() context manager.")
+
+    # Statistics and service info
+
+    async def get_compression_stats(self) -> Dict[str, Any]:
+        """Get compression and usage statistics from server."""
+        await self._ensure_client()
+
+        try:
+            response = await self._client.get("/stats")
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            logger.error(f"Stats request error: {e}")
+            return {"error": str(e)}
+
+    async def get_service_health(self) -> Dict[str, Any]:
+        """Get service health status."""
+        await self._ensure_client()
+
+        try:
+            response = await self._client.get("/health")
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            logger.error(f"Health check error: {e}")
+            return {"status": "unhealthy", "error": str(e)}
+
+    async def get_supported_formats(self) -> Dict[str, List[str]]:
+        """Get list of supported translation formats."""
+        await self._ensure_client()
+
+        try:
+            response = await self._client.get("/formats")
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            logger.error(f"Formats request error: {e}")
+            return {"error": str(e)}
+
+    async def get_symbol_families(self) -> Dict[str, Any]:
+        """Get information about emergent language symbol families."""
+        await self._ensure_client()
+
+        try:
+            response = await self._client.get("/symbols")
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            logger.error(f"Symbols request error: {e}")
+            return {"error": str(e)}
+
+    # Oracle-Enhanced Methods
+
+    async def explain_emergent_message(
+        self,
+        emergent_data: bytes,
+        mode: str = "verbose"
+    ) -> Dict[str, Any]:
+        """
+        Get human-readable explanation of emergent language symbols using Oracle.
+
+        Args:
+            emergent_data: Emergent language symbol bytes
+            mode: Explanation mode ("glyph", "verbose", "json")
+
+        Returns:
+            Oracle explanation with human-readable description
+        """
+        await self._ensure_client()
+
+        try:
+            # Encode as base64 for transport
+            encoded_data = base64.b64encode(emergent_data).decode('utf-8')
+
+            request_data = {
+                "emergent_data": encoded_data,
+                "mode": mode
+            }
+
+            response = await self._client.post("/oracle/explain", json=request_data)
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPError as e:
+            logger.error(f"Oracle explanation error: {e}")
+            return {"success": False, "error": str(e)}
+
+    async def validate_translation(
+        self,
+        original_data: Union[dict, str],
+        emergent_data: bytes
+    ) -> Dict[str, Any]:
+        """
+        Validate translation accuracy using Oracle confidence scoring.
+
+        Args:
+            original_data: Original data that was translated
+            emergent_data: Resulting emergent language bytes
+
+        Returns:
+            Validation result with confidence score and Oracle explanation
+        """
+        await self._ensure_client()
+
+        try:
+            # Encode as base64 for transport
+            encoded_data = base64.b64encode(emergent_data).decode('utf-8')
+
+            request_data = {
+                "original_data": original_data,
+                "emergent_data": encoded_data
+            }
+
+            response = await self._client.post("/oracle/validate", json=request_data)
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPError as e:
+            logger.error(f"Oracle validation error: {e}")
+            return {"success": False, "error": str(e)}
+
+    async def explain_symbol_families(
+        self,
+        emergent_data: bytes
+    ) -> Dict[str, Any]:
+        """
+        Get Oracle explanations for symbol families in emergent message.
+
+        Args:
+            emergent_data: Emergent language symbol bytes
+
+        Returns:
+            Dictionary with symbol family explanations and contexts
+        """
+        await self._ensure_client()
+
+        try:
+            # Encode as base64 for URL path
+            encoded_data = base64.b64encode(emergent_data).decode('utf-8')
+
+            response = await self._client.get(f"/oracle/symbols/{encoded_data}")
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPError as e:
+            logger.error(f"Symbol family explanation error: {e}")
+            return {"success": False, "error": str(e)}
+
+    # Internal helper methods
+
+    async def _make_translation_request(self, request_data: Dict[str, Any]) -> ClientTranslationResult:
+        """Make translation request with retry logic."""
+        last_error = None
+
+        for attempt in range(self.config.max_retries):
+            try:
+                response = await self._client.post("/translate", json=request_data)
+                response.raise_for_status()
+
+                result_data = response.json()
+
+                # Decode translated data if present
+                translated_data = None
+                if result_data.get("translated_data"):
+                    try:
+                        translated_data = base64.b64decode(result_data["translated_data"])
+                    except:
+                        # Fallback to string encoding if base64 decode fails
+                        translated_data = result_data["translated_data"].encode('utf-8')
+
+                return ClientTranslationResult(
+                    success=result_data.get("success", False),
+                    translated_data=translated_data,
+                    original_size=result_data.get("original_size", 0),
+                    translated_size=result_data.get("translated_size", 0),
+                    compression_ratio=result_data.get("compression_ratio", 0.0),
+                    efficiency_gain=result_data.get("efficiency_gain", 0.0),
+                    translation_time_ms=result_data.get("translation_time_ms", 0.0),
+                    symbol_count=result_data.get("symbol_count", 0),
+                    symbol_families=result_data.get("symbol_families", []),
+                    metadata=result_data.get("metadata", {}),
+                    errors=result_data.get("errors", [])
+                )
+
+            except httpx.HTTPError as e:
+                last_error = e
+                if attempt < self.config.max_retries - 1:
+                    await asyncio.sleep(self.config.retry_delay)
+                    continue
+                else:
+                    logger.error(f"Translation request failed after {self.config.max_retries} attempts: {e}")
+                    break
+
+            except Exception as e:
+                last_error = e
+                logger.error(f"Unexpected translation error: {e}")
+                break
+
+        return ClientTranslationResult(
+            success=False,
+            errors=[str(last_error)] if last_error else ["Unknown error"]
+        )
+
+
+class SyncEmergentTranslatorClient:
+    """
+    Synchronous client for Emergent Language Translator API.
+
+    Wrapper around async client for synchronous usage.
+    """
+
+    def __init__(self, config: Optional[TranslationConfig] = None):
+        """Initialize sync client."""
+        self.config = config or TranslationConfig()
+        self._async_client = EmergentTranslatorClient(config)
+
+    def __enter__(self):
+        """Sync context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Sync context manager exit."""
+        asyncio.run(self._async_client.close())
+
+    def translate_json(self, data: Union[dict, str], **kwargs) -> ClientTranslationResult:
+        """Sync version of translate_json."""
+        return asyncio.run(self._async_client.translate_json(data, **kwargs))
+
+    def translate_text(self, text: str, **kwargs) -> ClientTranslationResult:
+        """Sync version of translate_text."""
+        return asyncio.run(self._async_client.translate_text(text, **kwargs))
+
+    def translate_from_emergent(self, symbol_data: bytes, **kwargs) -> ClientTranslationResult:
+        """Sync version of translate_from_emergent."""
+        return asyncio.run(self._async_client.translate_from_emergent(symbol_data, **kwargs))
+
+    def translate_batch(self, requests: List[Dict[str, Any]], **kwargs) -> List[ClientTranslationResult]:
+        """Sync version of translate_batch."""
+        return asyncio.run(self._async_client.translate_batch(requests, **kwargs))
+
+    def get_compression_stats(self) -> Dict[str, Any]:
+        """Sync version of get_compression_stats."""
+        return asyncio.run(self._async_client.get_compression_stats())
+
+    def get_service_health(self) -> Dict[str, Any]:
+        """Sync version of get_service_health."""
+        return asyncio.run(self._async_client.get_service_health())
+
+    # Oracle-Enhanced Sync Methods
+
+    def explain_emergent_message(self, emergent_data: bytes, mode: str = "verbose") -> Dict[str, Any]:
+        """Sync version of explain_emergent_message."""
+        return asyncio.run(self._async_client.explain_emergent_message(emergent_data, mode))
+
+    def validate_translation(self, original_data: Union[dict, str], emergent_data: bytes) -> Dict[str, Any]:
+        """Sync version of validate_translation."""
+        return asyncio.run(self._async_client.validate_translation(original_data, emergent_data))
+
+    def explain_symbol_families(self, emergent_data: bytes) -> Dict[str, Any]:
+        """Sync version of explain_symbol_families."""
+        return asyncio.run(self._async_client.explain_symbol_families(emergent_data))
+
+
+# High-level SDK class
+
+class TranslatorSDK:
+    """
+    High-level SDK for Emergent Language Translation.
+
+    Provides the simplest possible interface for external AIs to integrate
+    with Eudaimonia's emergent language system.
+
+    Example:
+        sdk = TranslatorSDK(api_url="https://translator.eudaimonia.ai")
+
+        # Compress JSON data
+        compressed = sdk.compress({"task": "analyze market"})
+        print(f"60x smaller: {len(compressed)} bytes")
+
+        # Decompress back to JSON
+        original = sdk.decompress(compressed, format="json")
+    """
+
+    def __init__(self, api_url: str = "http://localhost:8000", auth_token: Optional[str] = None, api_key: Optional[str] = None):
+        """
+        Initialize SDK with API configuration.
+
+        Args:
+            api_url: Base URL of the translator API
+            auth_token: Optional authentication token
+            api_key: Alias for auth_token (for CLI compatibility)
+        """
+        token = auth_token or api_key
+        self.api_url = api_url
+        config = TranslationConfig(api_base_url=api_url, auth_token=token)
+        self.client = SyncEmergentTranslatorClient(config)
+
+    def compress(
+        self,
+        data: Union[dict, str],
+        intent: str = "general"
+    ) -> bytes:
+        """
+        Compress data to emergent language symbols.
+
+        Args:
+            data: JSON data or text string to compress
+            intent: Intent type for better compression
+
+        Returns:
+            Compressed emergent language bytes (typically 60x smaller)
+        """
+        if isinstance(data, dict):
+            result = self.client.translate_json(data, intent_type=intent)
+        elif isinstance(data, str):
+            result = self.client.translate_text(data, intent_type=intent)
+        else:
+            raise ValueError("Data must be dict or str")
+
+        if not result.success:
+            raise RuntimeError(f"Compression failed: {', '.join(result.errors)}")
+
+        return result.translated_data
+
+    def decompress(self, compressed_data: bytes, format: str = "json") -> Union[dict, str]:
+        """
+        Decompress emergent language symbols back to readable format.
+
+        Args:
+            compressed_data: Emergent language symbol bytes
+            format: Target format (json, text)
+
+        Returns:
+            Decompressed data
+        """
+        result = self.client.translate_from_emergent(compressed_data, target_format=format)
+
+        if not result.success:
+            raise RuntimeError(f"Decompression failed: {', '.join(result.errors)}")
+
+        if format == "json":
+            try:
+                return json.loads(result.translated_data.decode('utf-8'))
+            except:
+                return {"data": result.translated_data.decode('utf-8', errors='ignore')}
+        else:
+            return result.translated_data.decode('utf-8', errors='ignore')
+
+    def get_compression_ratio(self, data: Union[dict, str]) -> float:
+        """
+        Get compression ratio without actually compressing (estimate).
+
+        Args:
+            data: Data to analyze
+
+        Returns:
+            Estimated compression ratio (e.g., 0.016 for 60x compression)
+        """
+        if isinstance(data, dict):
+            original_size = len(json.dumps(data))
+        else:
+            original_size = len(data.encode('utf-8'))
+
+        # Typical emergent language message is 8-16 bytes
+        estimated_compressed_size = 12
+
+        return estimated_compressed_size / original_size
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get compression statistics from the service."""
+        return self.client.get_compression_stats()
+
+    def get_health(self) -> Dict[str, Any]:
+        """Get full health status from the service."""
+        return self.client.get_service_health()
+
+    def is_healthy(self) -> bool:
+        """Check if the translator service is healthy."""
+        health = self.get_health()
+        return health.get("status") == "healthy"
+
+    # Oracle-Powered Methods
+
+    def explain(self, compressed_data: bytes, mode: str = "verbose") -> str:
+        """
+        Get human explanation of compressed emergent data.
+
+        Args:
+            compressed_data: Emergent language bytes
+            mode: Explanation mode ("glyph", "verbose", "json")
+
+        Returns:
+            Human-readable explanation of what the symbols mean
+        """
+        result = self.client.explain_emergent_message(compressed_data, mode)
+        if result.get("success"):
+            return result.get("explanation", "No explanation available")
+        else:
+            raise RuntimeError(f"Oracle explanation failed: {result.get('error', 'Unknown error')}")
+
+    def validate(self, original_data: Union[dict, str], compressed_data: bytes) -> float:
+        """
+        Validate that compressed data preserves the meaning of original data.
+
+        Args:
+            original_data: Original data before compression
+            compressed_data: Compressed emergent language bytes
+
+        Returns:
+            Confidence score (0.0-1.0) indicating translation accuracy
+        """
+        result = self.client.validate_translation(original_data, compressed_data)
+        if result.get("success") and result.get("validation_available"):
+            return result.get("confidence_score", 0.0)
+        else:
+            raise RuntimeError(f"Oracle validation failed: {result.get('error', 'Unknown error')}")
+
+    def get_symbol_info(self, compressed_data: bytes) -> Dict[str, str]:
+        """
+        Get detailed information about symbol families in compressed data.
+
+        Args:
+            compressed_data: Emergent language bytes
+
+        Returns:
+            Dictionary mapping symbol families to their explanations
+        """
+        result = self.client.explain_symbol_families(compressed_data)
+        if result.get("success"):
+            return result.get("symbol_families", {})
+        else:
+            raise RuntimeError(f"Symbol explanation failed: {result.get('error', 'Unknown error')}")
+
+    def compress_with_explanation(
+        self,
+        data: Union[dict, str],
+        intent: str = "general"
+    ) -> Tuple[bytes, str]:
+        """
+        Compress data and get Oracle explanation in one call.
+
+        Args:
+            data: Data to compress
+            intent: Intent type for optimization
+
+        Returns:
+            Tuple of (compressed_bytes, human_explanation)
+        """
+        # Compress the data
+        compressed = self.compress(data, intent)
+
+        # Get Oracle explanation
+        explanation = self.explain(compressed)
+
+        return compressed, explanation
+
+
+# Convenience functions for quick usage
+
+def compress_json(data: dict, api_url: str = "http://localhost:8000") -> bytes:
+    """
+    Quick function to compress JSON data.
+
+    Args:
+        data: JSON data to compress
+        api_url: Translator API URL
+
+    Returns:
+        Compressed emergent language bytes
+    """
+    sdk = TranslatorSDK(api_url)
+    return sdk.compress(data)
+
+
+def decompress_to_json(compressed_data: bytes, api_url: str = "http://localhost:8000") -> dict:
+    """
+    Quick function to decompress to JSON.
+
+    Args:
+        compressed_data: Emergent language bytes
+        api_url: Translator API URL
+
+    Returns:
+        Decompressed JSON data
+    """
+    sdk = TranslatorSDK(api_url)
+    return sdk.decompress(compressed_data, format="json")
+
+
+# Oracle-Enhanced Convenience Functions
+
+def explain_emergent(compressed_data: bytes, api_url: str = "http://localhost:8000") -> str:
+    """
+    Quick function to get Oracle explanation of emergent data.
+
+    Args:
+        compressed_data: Emergent language bytes
+        api_url: Translator API URL
+
+    Returns:
+        Human-readable explanation
+    """
+    sdk = TranslatorSDK(api_url)
+    return sdk.explain(compressed_data)
+
+
+def validate_compression(
+    original_data: Union[dict, str],
+    compressed_data: bytes,
+    api_url: str = "http://localhost:8000"
+) -> float:
+    """
+    Quick function to validate compression accuracy.
+
+    Args:
+        original_data: Original data
+        compressed_data: Compressed bytes
+        api_url: Translator API URL
+
+    Returns:
+        Confidence score (0.0-1.0)
+    """
+    sdk = TranslatorSDK(api_url)
+    return sdk.validate(original_data, compressed_data)
+
+
+def compress_with_oracle(
+    data: Union[dict, str],
+    api_url: str = "http://localhost:8000"
+) -> Tuple[bytes, str]:
+    """
+    Quick function to compress data and get Oracle explanation.
+
+    Args:
+        data: Data to compress
+        api_url: Translator API URL
+
+    Returns:
+        Tuple of (compressed_bytes, explanation)
+    """
+    sdk = TranslatorSDK(api_url)
+    return sdk.compress_with_explanation(data)
+
+
+# Export main classes
+__all__ = [
+    'EmergentTranslatorClient',
+    'SyncEmergentTranslatorClient',
+    'TranslatorSDK',
+    'TranslationConfig',
+    'ClientTranslationResult',
+    'compress_json',
+    'decompress_to_json',
+    'explain_emergent',
+    'validate_compression',
+    'compress_with_oracle'
+]