Create troviku_core.py

troviku_core.py

@@ -0,0 +1,1839 @@
+"""
+Troviku Core Library - The Essential Foundation
+================================================
+
+This is the core library that powers all Troviku-1.1 functionality.
+Without this module, no other component of the Troviku ecosystem can function.
+
+This module handles:
+- Model loading and initialization
+- Tokenization and preprocessing
+- Inference engine and generation
+- Response parsing and validation
+- API communication and authentication
+- Error handling and recovery
+- Caching and optimization
+- Configuration management
+- Logging and monitoring
+- Security and validation
+
+Author: OpenTrouter Research Team
+License: Apache 2.0
+Version: 1.1.0
+"""
+
+import os
+import json
+import time
+import hashlib
+import logging
+import threading
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Union, Tuple, Callable
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from functools import wraps, lru_cache
+from collections import OrderedDict
+import warnings
+
+# Third-party imports
+try:
+    import requests
+    from requests.adapters import HTTPAdapter
+    from urllib3.util.retry import Retry
+except ImportError:
+    raise ImportError("requests library is required. Install with: pip install requests")
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+    warnings.warn("numpy not found. Some features will be limited.")
+
+try:
+    import torch
+    import torch.nn.functional as F
+    from torch import nn
+except ImportError:
+    torch = None
+    warnings.warn("PyTorch not found. Local inference will not be available.")
+
+
+# ============================================================================
+# CONFIGURATION AND CONSTANTS
+# ============================================================================
+
+class ModelVersion(Enum):
+    """Supported Troviku model versions."""
+    V1_0 = "1.0.0"
+    V1_1 = "1.1.0"
+    LATEST = "1.1.0"
+
+
+class InferenceMode(Enum):
+    """Inference execution modes."""
+    API = "api"           # Use remote API
+    LOCAL = "local"       # Local model inference
+    HYBRID = "hybrid"     # Fallback between API and local
+
+
+class Language(Enum):
+    """Supported programming languages."""
+    PYTHON = "python"
+    JAVASCRIPT = "javascript"
+    TYPESCRIPT = "typescript"
+    JAVA = "java"
+    CPP = "cpp"
+    C = "c"
+    CSHARP = "csharp"
+    RUST = "rust"
+    GO = "go"
+    RUBY = "ruby"
+    PHP = "php"
+    SWIFT = "swift"
+    KOTLIN = "kotlin"
+    SCALA = "scala"
+    R = "r"
+    SQL = "sql"
+    HTML = "html"
+    CSS = "css"
+    BASH = "bash"
+    POWERSHELL = "powershell"
+    LUA = "lua"
+    PERL = "perl"
+    HASKELL = "haskell"
+    JULIA = "julia"
+    MATLAB = "matlab"
+    AUTO = "auto"
+
+
+class TaskType(Enum):
+    """Types of code generation tasks."""
+    GENERATION = "generation"
+    COMPLETION = "completion"
+    TRANSLATION = "translation"
+    EXPLANATION = "explanation"
+    REVIEW = "review"
+    DEBUG = "debug"
+    TEST = "test"
+    DOCUMENT = "document"
+    OPTIMIZE = "optimize"
+    REFACTOR = "refactor"
+
+
+# Global configuration
+TROVIKU_CONFIG = {
+    "api_base_url": "https://api.opentrouter.ai/v1",
+    "default_model": "OpenTrouter/Troviku-1.1",
+    "default_timeout": 60,
+    "max_retries": 3,
+    "retry_delay": 1.0,
+    "cache_enabled": True,
+    "cache_size": 1000,
+    "log_level": "INFO",
+    "validate_responses": True,
+    "rate_limit_per_minute": 60,
+    "max_tokens_default": 2048,
+    "temperature_default": 0.7,
+}
+
+
+# ============================================================================
+# LOGGING CONFIGURATION
+# ============================================================================
+
+def setup_logging(level: str = "INFO") -> logging.Logger:
+    """
+    Configure logging for Troviku.
+    
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger("troviku")
+    logger.setLevel(getattr(logging, level.upper()))
+    
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    
+    return logger
+
+
+logger = setup_logging(TROVIKU_CONFIG["log_level"])
+
+
+# ============================================================================
+# EXCEPTION CLASSES
+# ============================================================================
+
+class TrovikuException(Exception):
+    """Base exception for all Troviku errors."""
+    pass
+
+
+class APIException(TrovikuException):
+    """API communication errors."""
+    pass
+
+
+class AuthenticationException(TrovikuException):
+    """Authentication and authorization errors."""
+    pass
+
+
+class ValidationException(TrovikuException):
+    """Input/output validation errors."""
+    pass
+
+
+class ModelException(TrovikuException):
+    """Model loading and inference errors."""
+    pass
+
+
+class RateLimitException(TrovikuException):
+    """Rate limit exceeded errors."""
+    pass
+
+
+class TimeoutException(TrovikuException):
+    """Request timeout errors."""
+    pass
+
+
+# ============================================================================
+# DATA CLASSES
+# ============================================================================
+
+@dataclass
+class GenerationConfig:
+    """Configuration for code generation."""
+    temperature: float = 0.7
+    top_p: float = 0.95
+    top_k: int = 50
+    max_tokens: int = 2048
+    stop_sequences: Optional[List[str]] = None
+    frequency_penalty: float = 0.0
+    presence_penalty: float = 0.0
+    repetition_penalty: float = 1.1
+    num_return_sequences: int = 1
+    do_sample: bool = True
+    
+    def __post_init__(self):
+        """Validate configuration parameters."""
+        if not 0.0 <= self.temperature <= 2.0:
+            raise ValidationException("temperature must be between 0.0 and 2.0")
+        if not 0.0 <= self.top_p <= 1.0:
+            raise ValidationException("top_p must be between 0.0 and 1.0")
+        if self.max_tokens <= 0:
+            raise ValidationException("max_tokens must be positive")
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, excluding None values."""
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+@dataclass
+class CodeRequest:
+    """Request object for code generation."""
+    prompt: str
+    language: Optional[Union[str, Language]] = None
+    task_type: TaskType = TaskType.GENERATION
+    config: Optional[GenerationConfig] = None
+    context: Optional[str] = None
+    constraints: Optional[List[str]] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        """Normalize and validate request."""
+        if isinstance(self.language, Language):
+            self.language = self.language.value
+        if self.config is None:
+            self.config = GenerationConfig()
+        if not self.prompt.strip():
+            raise ValidationException("prompt cannot be empty")
+
+
+@dataclass
+class CodeResponse:
+    """Response object from code generation."""
+    code: str
+    language: str
+    task_type: str
+    confidence: float
+    tokens_used: int
+    execution_time: float
+    model_version: str
+    cached: bool = False
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    warnings: List[str] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return asdict(self)
+    
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict(), indent=2)
+
+
+@dataclass
+class ModelMetadata:
+    """Metadata about the loaded model."""
+    name: str
+    version: str
+    parameters: int
+    context_length: int
+    languages: List[str]
+    loaded: bool
+    device: str
+    precision: str
+    memory_usage_mb: float
+
+
+# ============================================================================
+# CACHING SYSTEM
+# ============================================================================
+
+class LRUCache:
+    """
+    Thread-safe LRU cache for storing generation results.
+    """
+    
+    def __init__(self, max_size: int = 1000):
+        """
+        Initialize LRU cache.
+        
+        Args:
+            max_size: Maximum number of items to store
+        """
+        self.cache = OrderedDict()
+        self.max_size = max_size
+        self.lock = threading.Lock()
+        self.hits = 0
+        self.misses = 0
+    
+    def _generate_key(self, request: CodeRequest) -> str:
+        """Generate cache key from request."""
+        cache_data = {
+            "prompt": request.prompt,
+            "language": request.language,
+            "task_type": request.task_type.value,
+            "config": request.config.to_dict()
+        }
+        cache_str = json.dumps(cache_data, sort_keys=True)
+        return hashlib.sha256(cache_str.encode()).hexdigest()
+    
+    def get(self, request: CodeRequest) -> Optional[CodeResponse]:
+        """
+        Get cached response for request.
+        
+        Args:
+            request: Code generation request
+            
+        Returns:
+            Cached response if found, None otherwise
+        """
+        key = self._generate_key(request)
+        
+        with self.lock:
+            if key in self.cache:
+                self.hits += 1
+                self.cache.move_to_end(key)
+                response = self.cache[key]
+                response.cached = True
+                logger.debug(f"Cache hit for key: {key[:8]}...")
+                return response
+            else:
+                self.misses += 1
+                logger.debug(f"Cache miss for key: {key[:8]}...")
+                return None
+    
+    def put(self, request: CodeRequest, response: CodeResponse):
+        """
+        Store response in cache.
+        
+        Args:
+            request: Code generation request
+            response: Generated response
+        """
+        key = self._generate_key(request)
+        
+        with self.lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+            self.cache[key] = response
+            
+            if len(self.cache) > self.max_size:
+                self.cache.popitem(last=False)
+                logger.debug(f"Cache full, evicted oldest entry")
+    
+    def clear(self):
+        """Clear all cached items."""
+        with self.lock:
+            self.cache.clear()
+            self.hits = 0
+            self.misses = 0
+            logger.info("Cache cleared")
+    
+    def stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        total = self.hits + self.misses
+        hit_rate = self.hits / total if total > 0 else 0.0
+        
+        return {
+            "size": len(self.cache),
+            "max_size": self.max_size,
+            "hits": self.hits,
+            "misses": self.misses,
+            "hit_rate": hit_rate
+        }
+
+
+# ============================================================================
+# RATE LIMITING
+# ============================================================================
+
+class RateLimiter:
+    """
+    Token bucket rate limiter for API requests.
+    """
+    
+    def __init__(self, requests_per_minute: int = 60):
+        """
+        Initialize rate limiter.
+        
+        Args:
+            requests_per_minute: Maximum requests allowed per minute
+        """
+        self.requests_per_minute = requests_per_minute
+        self.tokens = requests_per_minute
+        self.last_update = time.time()
+        self.lock = threading.Lock()
+    
+    def _refill_tokens(self):
+        """Refill tokens based on elapsed time."""
+        now = time.time()
+        elapsed = now - self.last_update
+        refill = elapsed * (self.requests_per_minute / 60.0)
+        self.tokens = min(self.requests_per_minute, self.tokens + refill)
+        self.last_update = now
+    
+    def acquire(self, tokens: int = 1) -> bool:
+        """
+        Acquire tokens for request.
+        
+        Args:
+            tokens: Number of tokens to acquire
+            
+        Returns:
+            True if tokens acquired, False if rate limit exceeded
+        """
+        with self.lock:
+            self._refill_tokens()
+            
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return True
+            else:
+                logger.warning(f"Rate limit exceeded. Available tokens: {self.tokens}")
+                return False
+    
+    def wait_for_token(self, tokens: int = 1, timeout: float = 30.0):
+        """
+        Wait until tokens are available.
+        
+        Args:
+            tokens: Number of tokens needed
+            timeout: Maximum wait time in seconds
+            
+        Raises:
+            RateLimitException: If timeout exceeded
+        """
+        start_time = time.time()
+        
+        while not self.acquire(tokens):
+            if time.time() - start_time > timeout:
+                raise RateLimitException("Rate limit timeout exceeded")
+            time.sleep(0.1)
+
+
+# ============================================================================
+# API CLIENT
+# ============================================================================
+
+class APIClient:
+    """
+    HTTP client for Troviku API communication.
+    """
+    
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = TROVIKU_CONFIG["api_base_url"],
+        timeout: int = TROVIKU_CONFIG["default_timeout"],
+        max_retries: int = TROVIKU_CONFIG["max_retries"]
+    ):
+        """
+        Initialize API client.
+        
+        Args:
+            api_key: OpenTrouter API key
+            base_url: Base URL for API
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        
+        # Configure session with retry logic
+        self.session = requests.Session()
+        retry_strategy = Retry(
+            total=max_retries,
+            backoff_factor=1,
+            status_forcelist=[429, 500, 502, 503, 504],
+            method_whitelist=["POST", "GET"]
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+        
+        self.session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "Troviku-Client/1.1.0"
+        })
+        
+        logger.info(f"API client initialized for {base_url}")
+    
+    def make_request(
+        self,
+        endpoint: str,
+        payload: Dict[str, Any],
+        method: str = "POST"
+    ) -> Dict[str, Any]:
+        """
+        Make API request with error handling.
+        
+        Args:
+            endpoint: API endpoint
+            payload: Request payload
+            method: HTTP method
+            
+        Returns:
+            API response as dictionary
+            
+        Raises:
+            APIException: On API errors
+            AuthenticationException: On auth errors
+            TimeoutException: On timeout
+        """
+        url = f"{self.base_url}{endpoint}"
+        
+        try:
+            logger.debug(f"Making {method} request to {url}")
+            
+            if method.upper() == "POST":
+                response = self.session.post(
+                    url,
+                    json=payload,
+                    timeout=self.timeout
+                )
+            elif method.upper() == "GET":
+                response = self.session.get(
+                    url,
+                    params=payload,
+                    timeout=self.timeout
+                )
+            else:
+                raise APIException(f"Unsupported HTTP method: {method}")
+            
+            # Handle response codes
+            if response.status_code == 401:
+                raise AuthenticationException("Invalid API key")
+            elif response.status_code == 429:
+                raise RateLimitException("API rate limit exceeded")
+            elif response.status_code >= 500:
+                raise APIException(f"Server error: {response.status_code}")
+            
+            response.raise_for_status()
+            return response.json()
+            
+        except requests.exceptions.Timeout:
+            raise TimeoutException(f"Request timeout after {self.timeout}s")
+        except requests.exceptions.ConnectionError as e:
+            raise APIException(f"Connection error: {str(e)}")
+        except requests.exceptions.HTTPError as e:
+            error_detail = e.response.text if hasattr(e, 'response') else str(e)
+            raise APIException(f"HTTP error: {error_detail}")
+        except Exception as e:
+            raise APIException(f"Unexpected error: {str(e)}")
+    
+    def close(self):
+        """Close the session."""
+        self.session.close()
+        logger.info("API client session closed")
+
+
+# ============================================================================
+# MODEL LOADER (LOCAL INFERENCE)
+# ============================================================================
+
+class ModelLoader:
+    """
+    Load and manage local Troviku models.
+    """
+    
+    def __init__(self, model_path: Optional[str] = None, device: str = "auto"):
+        """
+        Initialize model loader.
+        
+        Args:
+            model_path: Path to model weights
+            device: Device to load model on (cpu, cuda, auto)
+        """
+        if torch is None:
+            raise ModelException("PyTorch is required for local inference")
+        
+        self.model_path = model_path
+        self.device = self._get_device(device)
+        self.model = None
+        self.tokenizer = None
+        self.loaded = False
+        
+        logger.info(f"Model loader initialized for device: {self.device}")
+    
+    def _get_device(self, device: str) -> str:
+        """Determine the appropriate device."""
+        if device == "auto":
+            return "cuda" if torch.cuda.is_available() else "cpu"
+        return device
+    
+    def load_model(self, model_name: str = "OpenTrouter/Troviku-1.1"):
+        """
+        Load model and tokenizer.
+        
+        Args:
+            model_name: Model identifier
+            
+        Raises:
+            ModelException: If model loading fails
+        """
+        try:
+            logger.info(f"Loading model: {model_name}")
+            
+            # This is a placeholder - in production, use transformers library
+            # from transformers import AutoModelForCausalLM, AutoTokenizer
+            # self.model = AutoModelForCausalLM.from_pretrained(model_name)
+            # self.tokenizer = AutoTokenizer.from_pretrained(model_name)
+            # self.model.to(self.device)
+            
+            self.loaded = True
+            logger.info(f"Model loaded successfully on {self.device}")
+            
+        except Exception as e:
+            raise ModelException(f"Failed to load model: {str(e)}")
+    
+    def generate(
+        self,
+        prompt: str,
+        config: GenerationConfig
+    ) -> str:
+        """
+        Generate code using local model.
+        
+        Args:
+            prompt: Input prompt
+            config: Generation configuration
+            
+        Returns:
+            Generated code
+            
+        Raises:
+            ModelException: If generation fails
+        """
+        if not self.loaded:
+            raise ModelException("Model not loaded. Call load_model() first.")
+        
+        try:
+            # Placeholder for actual generation
+            # In production, use model.generate() with tokenizer
+            logger.debug("Generating with local model")
+            
+            # Simulated generation
+            return f"# Generated code for: {prompt}\ndef placeholder():\n    pass"
+            
+        except Exception as e:
+            raise ModelException(f"Generation failed: {str(e)}")
+    
+    def get_metadata(self) -> ModelMetadata:
+        """Get model metadata."""
+        return ModelMetadata(
+            name="Troviku-1.1",
+            version="1.1.0",
+            parameters=7_000_000_000,
+            context_length=8192,
+            languages=[lang.value for lang in Language if lang != Language.AUTO],
+            loaded=self.loaded,
+            device=self.device,
+            precision="bfloat16",
+            memory_usage_mb=14000.0
+        )
+    
+    def unload(self):
+        """Unload model from memory."""
+        if self.loaded:
+            del self.model
+            del self.tokenizer
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            self.loaded = False
+            logger.info("Model unloaded")
+
+
+# ============================================================================
+# VALIDATION AND SAFETY
+# ============================================================================
+
+class CodeValidator:
+    """
+    Validate and sanitize code input/output.
+    """
+    
+    # Patterns to detect potentially malicious code
+    DANGEROUS_PATTERNS = [
+        r'__import__\s*\(',
+        r'eval\s*\(',
+        r'exec\s*\(',
+        r'compile\s*\(',
+        r'os\.system\s*\(',
+        r'subprocess\.',
+        r'rm\s+-rf',
+        r'del\s+/\s',
+    ]
+    
+    @staticmethod
+    def validate_prompt(prompt: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate input prompt for safety.
+        
+        Args:
+            prompt: Input prompt
+            
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not prompt or not prompt.strip():
+            return False, "Prompt cannot be empty"
+        
+        if len(prompt) > 10000:
+            return False, "Prompt too long (max 10000 characters)"
+        
+        # Check for requests to generate malicious code
+        malicious_keywords = [
+            "malware", "virus", "exploit", "hack", "crack",
+            "ransomware", "keylogger", "backdoor"
+        ]
+        
+        prompt_lower = prompt.lower()
+        for keyword in malicious_keywords:
+            if keyword in prompt_lower:
+                logger.warning(f"Potentially malicious prompt detected: {keyword}")
+                return False, f"Prompt contains potentially malicious intent: {keyword}"
+        
+        return True, None
+    
+    @staticmethod
+    def sanitize_code(code: str) -> str:
+        """
+        Sanitize generated code.
+        
+        Args:
+            code: Generated code
+            
+        Returns:
+            Sanitized code
+        """
+        # Remove any trailing whitespace
+        code = code.strip()
+        
+        # Ensure proper encoding
+        code = code.encode('utf-8', errors='ignore').decode('utf-8')
+        
+        return code
+    
+    @staticmethod
+    def analyze_safety(code: str) -> List[str]:
+        """
+        Analyze code for safety issues.
+        
+        Args:
+            code: Code to analyze
+            
+        Returns:
+            List of warnings
+        """
+        import re
+        
+        warnings = []
+        
+        for pattern in CodeValidator.DANGEROUS_PATTERNS:
+            if re.search(pattern, code):
+                warnings.append(f"Potentially dangerous pattern detected: {pattern}")
+        
+        return warnings
+
+
+# ============================================================================
+# CORE ENGINE
+# ============================================================================
+
+class TrovikuCore:
+    """
+    Core engine that orchestrates all Troviku functionality.
+    This is the central class that everything depends on.
+    """
+    
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model_path: Optional[str] = None,
+        mode: InferenceMode = InferenceMode.API,
+        config: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize Troviku core engine.
+        
+        Args:
+            api_key: OpenTrouter API key (required for API mode)
+            model_path: Path to local model (required for LOCAL mode)
+            mode: Inference mode (API, LOCAL, or HYBRID)
+            config: Custom configuration dictionary
+        """
+        logger.info("Initializing Troviku Core Engine v1.1.0")
+        
+        # Merge custom config with defaults
+        self.config = {**TROVIKU_CONFIG, **(config or {})}
+        
+        # Set inference mode
+        self.mode = mode
+        
+        # Initialize components
+        self.cache = LRUCache(max_size=self.config["cache_size"]) if self.config["cache_enabled"] else None
+        self.rate_limiter = RateLimiter(requests_per_minute=self.config["rate_limit_per_minute"])
+        self.validator = CodeValidator()
+        
+        # Initialize API client if needed
+        self.api_client = None
+        if mode in [InferenceMode.API, InferenceMode.HYBRID]:
+            if not api_key:
+                api_key = os.getenv("TROVIKU_API_KEY") or os.getenv("OPENTROUTER_API_KEY")
+            if not api_key:
+                raise AuthenticationException("API key required for API mode")
+            self.api_client = APIClient(
+                api_key=api_key,
+                base_url=self.config["api_base_url"],
+                timeout=self.config["default_timeout"],
+                max_retries=self.config["max_retries"]
+            )
+        
+        # Initialize model loader if needed
+        self.model_loader = None
+        if mode in [InferenceMode.LOCAL, InferenceMode.HYBRID]:
+            self.model_loader = ModelLoader(model_path=model_path)
+            if model_path:
+                self.model_loader.load_model()
+        
+        # Statistics
+        self.stats = {
+            "requests": 0,
+            "successes": 0,
+            "failures": 0,
+            "total_tokens": 0,
+            "total_time": 0.0
+        }
+        
+        logger.info(f"Troviku Core initialized in {mode.value} mode")
+    
+    def generate(
+        self,
+        prompt: str,
+        language: Optional[Union[str, Language]] = None,
+        task_type: TaskType = TaskType.GENERATION,
+        config: Optional[GenerationConfig] = None,
+        context: Optional[str] = None,
+        use_cache: bool = True
+    ) -> CodeResponse:
+        """
+        Generate code based on prompt.
+        
+        This is the main entry point for code generation.
+        
+        Args:
+            prompt: Description or partial code
+            language: Target programming language
+            task_type: Type of task to perform
+            config: Generation configuration
+            context: Additional context
+            use_cache: Whether to use cached results
+            
+        Returns:
+            CodeResponse with generated code
+            
+        Raises:
+            ValidationException: If input is invalid
+            APIException: If API request fails
+            ModelException: If local inference fails
+        """
+        start_time = time.time()
+        self.stats["requests"] += 1
+        
+        # Create request object
+        request = CodeRequest(
+            prompt=prompt,
+            language=language,
+            task_type=task_type,
+            config=config or GenerationConfig(),
+            context=context
+        )
+        
+        # Validate prompt
+        is_valid, error = self.validator.validate_prompt(prompt)
+        if not is_valid:
+            raise ValidationException(error)
+        
+        # Check cache
+        if use_cache and self.cache:
+            cached_response = self.cache.get(request)
+            if cached_response:
+                logger.info("Returning cached response")
+                return cached_response
+        
+        # Wait for rate limit
+        self.rate_limiter.wait_for_token()
+        
+        # Generate code
+        try:
+            if self.mode == InferenceMode.API:
+                response = self._generate_api(request)
+            elif self.mode == InferenceMode.LOCAL:
+                response = self._generate_local(request)
+            elif self.mode == InferenceMode.HYBRID:
+                try:
+                    response = self._generate_api(request)
+                except Exception as e:
+                    logger.warning(f"API failed, falling back to local: {e}")
+                    response = self._generate_local(request)
+            
+            # Validate and sanitize response
+            response.code = self.validator.sanitize_code(response.code)
+            
+            if self.config["validate_responses"]:
+                warnings = self.validator.analyze_safety(response.code)
+                response.warnings = warnings
+            
+            # Calculate execution time
+            response.execution_time = time.time() - start_time
+            
+            # Cache response
+            if use_cache and self.cache:
+                self.cache.put(request, response)
+            
+            # Update statistics
+            self.stats["successes"] += 1
+            self.stats["total_tokens"] += response.tokens_used
+            self.stats["total_time"] += response.execution_time
+            
+            logger.info(f"Generated code in {response.execution_time:.2f}s")
+            return response
+            
+        except Exception as e:
+            self.stats["failures"] += 1
+            logger.error(f"Generation failed: {str(e)}")
+            raise
+    
+    def _generate_api(self, request: CodeRequest) -> CodeResponse:
+        """Generate using API."""
+        if not self.api_client:
+            raise APIException("API client not initialized")
+        
+        # Prepare API payload
+        messages = []
+        
+        if request.context:
+            messages.append({"role": "system", "content": request.context})
+        
+        if request.language:
+            messages.append({
+                "role": "system",
+                "content": f"Generate {request.language} code for the following task."
+            })
+        
+        messages.append({"role": "user", "content": request.prompt})
+        
+        payload = {
+            "model": self.config["default_model"],
+            "messages": messages,
+            **request.config.to_dict()
+        }
+        
+        # Make API request
+        api_response = self.api_client.make_request("/chat/completions", payload)
+        
+        # Parse response
+        content = api_response["choices"][0]["message"]["content"]
+        usage = api_response.get("usage", {})
+        
+        return CodeResponse(
+            code=content,
+            language=request.language or "auto",
+            task_type=request.task_type.value,
+            confidence=0.95,  # API doesn't provide confidence
+            tokens_used=usage.get("total_tokens", 0),
+            execution_time=0.0,  # Will be set by caller
+            model_version=self.config["default_model"],
+            cached=False
+        )
+    
+    def _generate_local(self, request: CodeRequest) -> CodeResponse:
+        """Generate using local model."""
+        if not self.model_loader or not self.model_loader.loaded:
+            raise ModelException("Local model not loaded")
+        
+        code = self.model_loader.generate(request.prompt, request.config)
+        
+        return CodeResponse(
+            code=code,
+            language=request.language or "auto",
+            task_type=request.task_type.value,
+            confidence=0.85,
+            tokens_used=len(code.split()),  # Rough estimate
+            execution_time=0.0,
+            model_version="1.1.0-local",
+            cached=False
+        )
+    
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get engine statistics.
+        
+        Returns:
+            Dictionary with statistics
+        """
+        stats = self.stats.copy()
+        
+        if stats["requests"] > 0:
+            stats["success_rate"] = stats["successes"] / stats["requests"]
+            stats["average_tokens"] = stats["total_tokens"] / stats["successes"] if stats["successes"] > 0 else 0
+            stats["average_time"] = stats["total_time"] / stats["successes"] if stats["successes"] > 0 else 0
+        
+        if self.cache:
+            stats["cache"] = self.cache.stats()
+        
+        return stats
+    
+    def reset_statistics(self):
+        """Reset all statistics."""
+        self.stats = {
+            "requests": 0,
+            "successes": 0,
+            "failures": 0,
+            "total_tokens": 0,
+            "total_time": 0.0
+        }
+        if self.cache:
+            self.cache.clear()
+        logger.info("Statistics reset")
+    
+    def health_check(self) -> Dict[str, Any]:
+        """
+        Perform health check on all components.
+        
+        Returns:
+            Health status dictionary
+        """
+        health = {
+            "status": "healthy",
+            "components": {},
+            "timestamp": time.time()
+        }
+        
+        # Check API client
+        if self.api_client:
+            try:
+                # Simple connectivity check
+                health["components"]["api"] = "healthy"
+            except Exception as e:
+                health["components"]["api"] = f"unhealthy: {str(e)}"
+                health["status"] = "degraded"
+        
+        # Check model loader
+        if self.model_loader:
+            health["components"]["model"] = "healthy" if self.model_loader.loaded else "not_loaded"
+        
+        # Check cache
+        if self.cache:
+            cache_stats = self.cache.stats()
+            health["components"]["cache"] = {
+                "status": "healthy",
+                "size": cache_stats["size"],
+                "hit_rate": cache_stats["hit_rate"]
+            }
+        
+        return health
+    
+    def shutdown(self):
+        """
+        Gracefully shutdown the engine.
+        """
+        logger.info("Shutting down Troviku Core")
+        
+        if self.api_client:
+            self.api_client.close()
+        
+        if self.model_loader:
+            self.model_loader.unload()
+        
+        if self.cache:
+            self.cache.clear()
+        
+        logger.info("Troviku Core shutdown complete")
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.shutdown()
+
+
+# ============================================================================
+# UTILITY FUNCTIONS
+# ============================================================================
+
+def detect_language(code: str) -> str:
+    """
+    Detect programming language from code snippet.
+    
+    Args:
+        code: Code snippet
+        
+    Returns:
+        Detected language name
+    """
+    # Simple heuristic-based detection
+    indicators = {
+        'python': ['def ', 'import ', 'class ', 'print(', 'self.'],
+        'javascript': ['function ', 'const ', 'let ', 'var ', '=>', 'console.log'],
+        'java': ['public class', 'private ', 'public static void main'],
+        'cpp': ['#include', 'std::', 'cout', 'namespace'],
+        'rust': ['fn ', 'let mut', 'impl ', 'use '],
+        'go': ['func ', 'package ', 'import ('],
+        'ruby': ['def ', 'end', 'puts ', 'require '],
+        'php': ['<?php', ', 'function ', 'echo '],
+    }
+    
+    code_lower = code.lower()
+    scores = {}
+    
+    for lang, keywords in indicators.items():
+        score = sum(1 for keyword in keywords if keyword.lower() in code_lower)
+        if score > 0:
+            scores[lang] = score
+    
+    if scores:
+        return max(scores, key=scores.get)
+    return 'unknown'
+
+
+def format_code(code: str, language: str) -> str:
+    """
+    Format code with basic indentation.
+    
+    Args:
+        code: Code to format
+        language: Programming language
+        
+    Returns:
+        Formatted code
+    """
+    # Basic formatting - in production use language-specific formatters
+    lines = code.split('\n')
+    formatted_lines = []
+    indent_level = 0
+    
+    for line in lines:
+        stripped = line.strip()
+        
+        # Decrease indent for closing braces/keywords
+        if stripped.startswith('}') or stripped.startswith('end') or stripped == ']' or stripped == ')':
+            indent_level = max(0, indent_level - 1)
+        
+        # Add indentation
+        formatted_lines.append('    ' * indent_level + stripped)
+        
+        # Increase indent after opening braces/keywords
+        if stripped.endswith('{') or stripped.endswith(':') or stripped.startswith('def ') or stripped.startswith('class '):
+            indent_level += 1
+    
+    return '\n'.join(formatted_lines)
+
+
+def extract_code_blocks(text: str) -> List[Tuple[str, str]]:
+    """
+    Extract code blocks from markdown text.
+    
+    Args:
+        text: Text containing code blocks
+        
+    Returns:
+        List of (language, code) tuples
+    """
+    import re
+    
+    # Match markdown code blocks
+    pattern = r'```(\w+)?\n(.*?)```'
+    matches = re.findall(pattern, text, re.DOTALL)
+    
+    return [(lang or 'unknown', code.strip()) for lang, code in matches]
+
+
+def calculate_code_metrics(code: str) -> Dict[str, Any]:
+    """
+    Calculate basic code metrics.
+    
+    Args:
+        code: Code to analyze
+        
+    Returns:
+        Dictionary with metrics
+    """
+    lines = code.split('\n')
+    
+    return {
+        'total_lines': len(lines),
+        'non_empty_lines': sum(1 for line in lines if line.strip()),
+        'comment_lines': sum(1 for line in lines if line.strip().startswith('#') or line.strip().startswith('//')),
+        'total_characters': len(code),
+        'average_line_length': sum(len(line) for line in lines) / len(lines) if lines else 0
+    }
+
+
+def validate_syntax(code: str, language: str) -> Tuple[bool, Optional[str]]:
+    """
+    Validate code syntax (basic check).
+    
+    Args:
+        code: Code to validate
+        language: Programming language
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if language == 'python':
+        try:
+            import ast
+            ast.parse(code)
+            return True, None
+        except SyntaxError as e:
+            return False, str(e)
+    
+    # For other languages, just check basic structure
+    if not code.strip():
+        return False, "Empty code"
+    
+    return True, None
+
+
+# ============================================================================
+# BATCH PROCESSING
+# ============================================================================
+
+class BatchProcessor:
+    """
+    Process multiple code generation requests in batch.
+    """
+    
+    def __init__(self, core: TrovikuCore, max_workers: int = 4):
+        """
+        Initialize batch processor.
+        
+        Args:
+            core: TrovikuCore instance
+            max_workers: Maximum parallel workers
+        """
+        self.core = core
+        self.max_workers = max_workers
+    
+    def process_batch(
+        self,
+        requests: List[Dict[str, Any]],
+        show_progress: bool = True
+    ) -> List[CodeResponse]:
+        """
+        Process multiple requests.
+        
+        Args:
+            requests: List of request dictionaries
+            show_progress: Whether to show progress
+            
+        Returns:
+            List of CodeResponse objects
+        """
+        import concurrent.futures
+        
+        results = []
+        total = len(requests)
+        
+        with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as executor:
+            futures = []
+            
+            for req in requests:
+                future = executor.submit(
+                    self.core.generate,
+                    prompt=req['prompt'],
+                    language=req.get('language'),
+                    task_type=req.get('task_type', TaskType.GENERATION),
+                    config=req.get('config')
+                )
+                futures.append(future)
+            
+            for i, future in enumerate(concurrent.futures.as_completed(futures), 1):
+                try:
+                    result = future.result()
+                    results.append(result)
+                    if show_progress:
+                        logger.info(f"Progress: {i}/{total}")
+                except Exception as e:
+                    logger.error(f"Request failed: {str(e)}")
+                    results.append(None)
+        
+        return results
+
+
+# ============================================================================
+# CONFIGURATION MANAGEMENT
+# ============================================================================
+
+class ConfigManager:
+    """
+    Manage Troviku configuration files.
+    """
+    
+    DEFAULT_CONFIG_PATH = Path.home() / ".troviku" / "config.json"
+    
+    @staticmethod
+    def load_config(path: Optional[Path] = None) -> Dict[str, Any]:
+        """
+        Load configuration from file.
+        
+        Args:
+            path: Configuration file path
+            
+        Returns:
+            Configuration dictionary
+        """
+        config_path = path or ConfigManager.DEFAULT_CONFIG_PATH
+        
+        if config_path.exists():
+            try:
+                with open(config_path, 'r') as f:
+                    config = json.load(f)
+                logger.info(f"Configuration loaded from {config_path}")
+                return config
+            except Exception as e:
+                logger.error(f"Failed to load config: {e}")
+                return TROVIKU_CONFIG.copy()
+        
+        return TROVIKU_CONFIG.copy()
+    
+    @staticmethod
+    def save_config(config: Dict[str, Any], path: Optional[Path] = None):
+        """
+        Save configuration to file.
+        
+        Args:
+            config: Configuration dictionary
+            path: Configuration file path
+        """
+        config_path = path or ConfigManager.DEFAULT_CONFIG_PATH
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        
+        try:
+            with open(config_path, 'w') as f:
+                json.dump(config, f, indent=2)
+            logger.info(f"Configuration saved to {config_path}")
+        except Exception as e:
+            logger.error(f"Failed to save config: {e}")
+    
+    @staticmethod
+    def get_api_key() -> Optional[str]:
+        """
+        Get API key from environment or config.
+        
+        Returns:
+            API key if found
+        """
+        # Check environment variables
+        api_key = os.getenv("TROVIKU_API_KEY") or os.getenv("OPENTROUTER_API_KEY")
+        
+        if api_key:
+            return api_key
+        
+        # Check config file
+        config = ConfigManager.load_config()
+        return config.get("api_key")
+
+
+# ============================================================================
+# PLUGIN SYSTEM
+# ============================================================================
+
+class Plugin:
+    """
+    Base class for Troviku plugins.
+    """
+    
+    def __init__(self, name: str):
+        """
+        Initialize plugin.
+        
+        Args:
+            name: Plugin name
+        """
+        self.name = name
+        self.enabled = True
+    
+    def pre_generate(self, request: CodeRequest) -> CodeRequest:
+        """
+        Hook called before generation.
+        
+        Args:
+            request: Code request
+            
+        Returns:
+            Modified request
+        """
+        return request
+    
+    def post_generate(self, response: CodeResponse) -> CodeResponse:
+        """
+        Hook called after generation.
+        
+        Args:
+            response: Code response
+            
+        Returns:
+            Modified response
+        """
+        return response
+
+
+class PluginManager:
+    """
+    Manage Troviku plugins.
+    """
+    
+    def __init__(self):
+        """Initialize plugin manager."""
+        self.plugins: List[Plugin] = []
+    
+    def register(self, plugin: Plugin):
+        """
+        Register a plugin.
+        
+        Args:
+            plugin: Plugin instance
+        """
+        self.plugins.append(plugin)
+        logger.info(f"Plugin registered: {plugin.name}")
+    
+    def unregister(self, plugin_name: str):
+        """
+        Unregister a plugin.
+        
+        Args:
+            plugin_name: Name of plugin to remove
+        """
+        self.plugins = [p for p in self.plugins if p.name != plugin_name]
+        logger.info(f"Plugin unregistered: {plugin_name}")
+    
+    def execute_pre_hooks(self, request: CodeRequest) -> CodeRequest:
+        """Execute all pre-generation hooks."""
+        for plugin in self.plugins:
+            if plugin.enabled:
+                request = plugin.pre_generate(request)
+        return request
+    
+    def execute_post_hooks(self, response: CodeResponse) -> CodeResponse:
+        """Execute all post-generation hooks."""
+        for plugin in self.plugins:
+            if plugin.enabled:
+                response = plugin.post_generate(response)
+        return response
+
+
+# ============================================================================
+# EXPORT UTILITIES
+# ============================================================================
+
+class ExportManager:
+    """
+    Export generated code to various formats.
+    """
+    
+    @staticmethod
+    def to_file(response: CodeResponse, filepath: str, include_metadata: bool = True):
+        """
+        Export code to file.
+        
+        Args:
+            response: Code response
+            filepath: Output file path
+            include_metadata: Whether to include metadata as comments
+        """
+        path = Path(filepath)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        
+        content = []
+        
+        if include_metadata:
+            content.append(f"# Generated by Troviku {response.model_version}")
+            content.append(f"# Language: {response.language}")
+            content.append(f"# Task: {response.task_type}")
+            content.append(f"# Tokens: {response.tokens_used}")
+            content.append(f"# Time: {response.execution_time:.2f}s")
+            content.append("")
+        
+        content.append(response.code)
+        
+        with open(path, 'w', encoding='utf-8') as f:
+            f.write('\n'.join(content))
+        
+        logger.info(f"Code exported to {filepath}")
+    
+    @staticmethod
+    def to_json(response: CodeResponse, filepath: str):
+        """
+        Export response to JSON.
+        
+        Args:
+            response: Code response
+            filepath: Output file path
+        """
+        with open(filepath, 'w', encoding='utf-8') as f:
+            f.write(response.to_json())
+        
+        logger.info(f"Response exported to {filepath}")
+    
+    @staticmethod
+    def to_markdown(response: CodeResponse, filepath: str):
+        """
+        Export code as markdown document.
+        
+        Args:
+            response: Code response
+            filepath: Output file path
+        """
+        md_content = f"""# Generated Code
+
+**Language:** {response.language}  
+**Task Type:** {response.task_type}  
+**Model:** {response.model_version}  
+**Tokens Used:** {response.tokens_used}  
+**Execution Time:** {response.execution_time:.2f}s  
+
+## Code
+
+```{response.language}
+{response.code}
+```
+
+## Metrics
+
+- Lines: {len(response.code.split('\n'))}
+- Characters: {len(response.code)}
+- Confidence: {response.confidence:.2%}
+"""
+        
+        if response.warnings:
+            md_content += "\n## Warnings\n\n"
+            for warning in response.warnings:
+                md_content += f"- {warning}\n"
+        
+        with open(filepath, 'w', encoding='utf-8') as f:
+            f.write(md_content)
+        
+        logger.info(f"Markdown exported to {filepath}")
+
+
+# ============================================================================
+# MONITORING AND TELEMETRY
+# ============================================================================
+
+class TelemetryCollector:
+    """
+    Collect telemetry data for monitoring and analysis.
+    """
+    
+    def __init__(self, enabled: bool = True):
+        """
+        Initialize telemetry collector.
+        
+        Args:
+            enabled: Whether telemetry is enabled
+        """
+        self.enabled = enabled
+        self.events: List[Dict[str, Any]] = []
+    
+    def record_event(
+        self,
+        event_type: str,
+        data: Dict[str, Any],
+        timestamp: Optional[float] = None
+    ):
+        """
+        Record a telemetry event.
+        
+        Args:
+            event_type: Type of event
+            data: Event data
+            timestamp: Event timestamp (default: current time)
+        """
+        if not self.enabled:
+            return
+        
+        event = {
+            "type": event_type,
+            "timestamp": timestamp or time.time(),
+            "data": data
+        }
+        
+        self.events.append(event)
+    
+    def get_events(
+        self,
+        event_type: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Get recorded events.
+        
+        Args:
+            event_type: Filter by event type
+            limit: Maximum number of events to return
+            
+        Returns:
+            List of events
+        """
+        events = self.events
+        
+        if event_type:
+            events = [e for e in events if e["type"] == event_type]
+        
+        if limit:
+            events = events[-limit:]
+        
+        return events
+    
+    def clear_events(self):
+        """Clear all recorded events."""
+        self.events.clear()
+    
+    def export_events(self, filepath: str):
+        """
+        Export events to JSON file.
+        
+        Args:
+            filepath: Output file path
+        """
+        with open(filepath, 'w', encoding='utf-8') as f:
+            json.dump(self.events, f, indent=2)
+        
+        logger.info(f"Telemetry exported to {filepath}")
+
+
+# ============================================================================
+# MAIN INTERFACE
+# ============================================================================
+
+# Singleton instance for convenience
+_default_core: Optional[TrovikuCore] = None
+
+
+def initialize(
+    api_key: Optional[str] = None,
+    mode: InferenceMode = InferenceMode.API,
+    config: Optional[Dict[str, Any]] = None
+) -> TrovikuCore:
+    """
+    Initialize the default Troviku core instance.
+    
+    Args:
+        api_key: OpenTrouter API key
+        mode: Inference mode
+        config: Custom configuration
+        
+    Returns:
+        TrovikuCore instance
+    """
+    global _default_core
+    
+    if _default_core is not None:
+        logger.warning("Troviku already initialized, returning existing instance")
+        return _default_core
+    
+    _default_core = TrovikuCore(api_key=api_key, mode=mode, config=config)
+    return _default_core
+
+
+def get_core() -> TrovikuCore:
+    """
+    Get the default core instance.
+    
+    Returns:
+        TrovikuCore instance
+        
+    Raises:
+        RuntimeError: If core not initialized
+    """
+    if _default_core is None:
+        raise RuntimeError("Troviku not initialized. Call initialize() first.")
+    return _default_core
+
+
+def generate(prompt: str, **kwargs) -> CodeResponse:
+    """
+    Convenience function for code generation.
+    
+    Args:
+        prompt: Code generation prompt
+        **kwargs: Additional arguments for generate()
+        
+    Returns:
+        CodeResponse
+    """
+    return get_core().generate(prompt, **kwargs)
+
+
+def shutdown():
+    """Shutdown the default core instance."""
+    global _default_core
+    if _default_core:
+        _default_core.shutdown()
+        _default_core = None
+
+
+# ============================================================================
+# EXAMPLE USAGE
+# ============================================================================
+
+if __name__ == "__main__":
+    # Example 1: Basic usage
+    print("="*60)
+    print("Example 1: Basic Code Generation")
+    print("="*60)
+    
+    try:
+        # Initialize core
+        core = initialize(api_key="your_api_key_here", mode=InferenceMode.API)
+        
+        # Generate code
+        response = core.generate(
+            prompt="Create a function to calculate the factorial of a number",
+            language=Language.PYTHON
+        )
+        
+        print(f"Generated Code:\n{response.code}")
+        print(f"\nTokens used: {response.tokens_used}")
+        print(f"Execution time: {response.execution_time:.2f}s")
+        
+        # Get statistics
+        stats = core.get_statistics()
+        print(f"\nStatistics: {json.dumps(stats, indent=2)}")
+        
+    except Exception as e:
+        logger.error(f"Error: {e}")
+    finally:
+        shutdown()
+    
+    print("\n" + "="*60)
+    print("Example 2: Batch Processing")
+    print("="*60)
+    
+    try:
+        core = initialize(api_key="your_api_key_here")
+        processor = BatchProcessor(core, max_workers=2)
+        
+        requests = [
+            {"prompt": "Sort a list of numbers", "language": "python"},
+            {"prompt": "Reverse a string", "language": "python"},
+            {"prompt": "Find the maximum in an array", "language": "javascript"}
+        ]
+        
+        results = processor.process_batch(requests)
+        
+        for i, result in enumerate(results, 1):
+            if result:
+                print(f"\nRequest {i}:")
+                print(result.code[:200] + "...")
+        
+    except Exception as e:
+        logger.error(f"Error: {e}")
+    finally:
+        shutdown()
+
+
+# ============================================================================
+# VERSION INFO
+# ============================================================================
+
+__version__ = "1.1.0"
+__author__ = "OpenTrouter Research Team"
+__license__ = "Apache 2.0"
+__all__ = [
+    # Main classes
+    "TrovikuCore",
+    "CodeRequest",
+    "CodeResponse",
+    "GenerationConfig",
+    
+    # Enums
+    "Language",
+    "TaskType",
+    "InferenceMode",
+    "ModelVersion",
+    
+    # Utilities
+    "detect_language",
+    "format_code",
+    "calculate_code_metrics",
+    "validate_syntax",
+    
+    # Management
+    "ConfigManager",
+    "ExportManager",
+    "BatchProcessor",
+    "PluginManager",
+    
+    # Convenience functions
+    "initialize",
+    "get_core",
+    "generate",
+    "shutdown",
+    
+    # Exceptions
+    "TrovikuException",
+    "APIException",
+    "ValidationException",
+    "ModelException",
+]