quantum-framework 0.9.0__py3-none-any.whl

quantum/runtime/api_server.py

@@ -0,0 +1,86 @@
+"""
+Quantum API Server - API server for Quantum microservices
+"""
+
+import sys
+from pathlib import Path
+from flask import Flask, jsonify, request
+import json
+from typing import Dict, Any
+
+# Fix imports
+
+from quantum.core.ast_nodes import ApplicationNode, QuantumRoute
+
+class QuantumAPIServer:
+    """API server for Quantum microservices"""
+    
+    def __init__(self, port: int = 8080):
+        self.port = port
+        self.app = Flask(__name__)
+        self.routes: Dict[str, Dict[str, Any]] = {}
+        self._setup_default_routes()
+    
+    def _setup_default_routes(self):
+        """Configure default API routes"""
+        @self.app.route('/health', methods=['GET'])
+        def health_check():
+            return jsonify({
+                "status": "healthy",
+                "server": "Quantum API",
+                "routes": list(self.routes.keys())
+            })
+    
+    def configure_from_ast(self, app_node: ApplicationNode):
+        """Configure API based on application AST"""
+        for route in app_node.routes:
+            self._add_route_from_ast(route)
+    
+    def _add_route_from_ast(self, route: QuantumRoute):
+        """Add API route based on AST"""
+        path = route.path
+        method = route.method
+        
+        # Get first q:return from route
+        content = "{}"
+        if route.returns:
+            content = route.returns[0].value or "{}"
+        
+        self._add_api_route(path, method, content)
+    
+    def _add_api_route(self, path: str, method: str, content: str):
+        """Add API route to Flask"""
+        self.routes[path] = {'method': method, 'content': content}
+        
+        def api_handler():
+            return self._process_json_content(content)
+        
+        # Unique name for function
+        api_handler.__name__ = f"api_{path.replace('/', '_').replace('-', '_')}"
+        
+        # Add to Flask
+        self.app.add_url_rule(path, api_handler.__name__, api_handler, methods=[method])
+    
+    def _process_json_content(self, content: str):
+        """Process content as JSON"""
+        try:
+            # Try to parse JSON
+            parsed = json.loads(content)
+            return jsonify(parsed)
+        except json.JSONDecodeError:
+            # If not valid JSON, return as text
+            return jsonify({"result": content, "type": "text"})
+    
+    def start(self):
+        """Start API server"""
+        print(f"🛠️  Quantum API Server starting on port {self.port}")
+        print(f"🔗 API: http://localhost:{self.port}")
+        print(f"🩺 Health: http://localhost:{self.port}/health")
+        print("🛑 To stop: Ctrl+C")
+        
+        try:
+            self.app.run(host='0.0.0.0', port=self.port, debug=False)
+        except KeyboardInterrupt:
+            print("\n👋 API server stopped by user")
+        except Exception as e:
+            print(f"❌ Server error: {e}")

quantum/runtime/ast_cache.py

@@ -0,0 +1,506 @@
+"""
+AST Cache - Phase 2 Performance Optimization
+
+Caches parsed AST structures for faster component loading.
+Uses mtime-based invalidation to detect file changes.
+
+Performance Impact:
+- 10-50x speedup on subsequent file loads
+- Automatic invalidation when files change
+- LRU eviction with configurable size
+- Thread-safe implementation
+"""
+
+import os
+import hashlib
+import threading
+import time
+import pickle
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple, List
+from dataclasses import dataclass, field
+from functools import lru_cache
+import weakref
+
+
+@dataclass
+class CacheEntry:
+    """A cached AST entry with metadata"""
+    ast: Any  # ComponentNode
+    mtime: float  # File modification time
+    size: int  # File size in bytes
+    hash: str  # Content hash for extra validation
+    created_at: float = field(default_factory=time.time)
+    access_count: int = 0
+    last_accessed: float = field(default_factory=time.time)
+
+    def touch(self):
+        """Update access statistics"""
+        self.access_count += 1
+        self.last_accessed = time.time()
+
+
+@dataclass
+class CacheStats:
+    """Statistics for cache performance monitoring"""
+    hits: int = 0
+    misses: int = 0
+    invalidations: int = 0
+    evictions: int = 0
+    total_parse_time_ms: float = 0.0
+    total_cache_time_ms: float = 0.0
+    entries_count: int = 0
+    memory_estimate_kb: float = 0.0
+
+    @property
+    def hit_rate(self) -> float:
+        total = self.hits + self.misses
+        return self.hits / total if total > 0 else 0.0
+
+    @property
+    def avg_parse_time_ms(self) -> float:
+        return self.total_parse_time_ms / self.misses if self.misses > 0 else 0.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            'hits': self.hits,
+            'misses': self.misses,
+            'hit_rate': f"{self.hit_rate:.1%}",
+            'invalidations': self.invalidations,
+            'evictions': self.evictions,
+            'entries_count': self.entries_count,
+            'memory_estimate_kb': f"{self.memory_estimate_kb:.1f}",
+            'avg_parse_time_ms': f"{self.avg_parse_time_ms:.2f}",
+        }
+
+
+class ASTCache:
+    """
+    Thread-safe LRU cache for parsed AST structures.
+
+    Features:
+    - Caches parsed ComponentNode objects by file path
+    - Automatic invalidation based on file mtime and size
+    - Optional content hash validation for extra safety
+    - LRU eviction with configurable max entries
+    - Statistics tracking for monitoring
+    - Filesystem watch integration support
+
+    Usage:
+        cache = ASTCache(max_entries=100)
+
+        # Get cached AST or parse if needed
+        ast = cache.get_or_parse("app.q", parser)
+
+        # Manual invalidation
+        cache.invalidate("app.q")
+
+        # Check statistics
+        print(cache.stats.hit_rate)
+    """
+
+    def __init__(
+        self,
+        max_entries: int = 100,
+        enable_hash_validation: bool = False,
+        enable_stats: bool = True,
+        cache_dir: Optional[Path] = None,
+    ):
+        """
+        Initialize the AST cache.
+
+        Args:
+            max_entries: Maximum number of AST entries to cache
+            enable_hash_validation: Whether to validate content hash (slower but safer)
+            enable_stats: Whether to track performance statistics
+            cache_dir: Optional directory for persistent cache (not implemented yet)
+        """
+        self._max_entries = max_entries
+        self._enable_hash = enable_hash_validation
+        self._enable_stats = enable_stats
+        self._cache_dir = cache_dir
+
+        self._cache: Dict[str, CacheEntry] = {}
+        self._stats = CacheStats()
+        self._lock = threading.RLock()
+
+        # For dependency tracking (imports)
+        self._dependencies: Dict[str, set] = {}  # file -> set of files it imports
+
+    def _normalize_path(self, file_path: Any) -> str:
+        """Normalize a file path to a canonical string key"""
+        if isinstance(file_path, Path):
+            return str(file_path.resolve())
+        return str(Path(file_path).resolve())
+
+    def _compute_hash(self, content: str) -> str:
+        """Compute a hash of the file content"""
+        return hashlib.md5(content.encode('utf-8')).hexdigest()
+
+    def _get_file_info(self, file_path: str) -> Tuple[float, int]:
+        """Get file mtime and size"""
+        try:
+            stat = os.stat(file_path)
+            return stat.st_mtime, stat.st_size
+        except OSError:
+            return 0.0, 0
+
+    def _is_valid(self, entry: CacheEntry, file_path: str, content: Optional[str] = None) -> bool:
+        """Check if a cache entry is still valid"""
+        mtime, size = self._get_file_info(file_path)
+
+        # Check mtime and size
+        if entry.mtime != mtime or entry.size != size:
+            return False
+
+        # Optionally check content hash
+        if self._enable_hash and content is not None:
+            content_hash = self._compute_hash(content)
+            if entry.hash != content_hash:
+                return False
+
+        return True
+
+    def _evict_lru(self):
+        """Evict least recently used entries if over capacity"""
+        while len(self._cache) >= self._max_entries:
+            # Find LRU entry
+            lru_key = min(
+                self._cache.keys(),
+                key=lambda k: self._cache[k].last_accessed
+            )
+            del self._cache[lru_key]
+            if self._enable_stats:
+                self._stats.evictions += 1
+
+    def _estimate_memory(self, ast: Any) -> float:
+        """Estimate memory usage of an AST in KB"""
+        try:
+            # Rough estimate using pickle size
+            data = pickle.dumps(ast)
+            return len(data) / 1024
+        except:
+            return 10.0  # Default estimate
+
+    def get(self, file_path: Any) -> Optional[Any]:
+        """
+        Get a cached AST if available and valid.
+
+        Args:
+            file_path: Path to the .q file
+
+        Returns:
+            Cached ComponentNode or None if not cached/invalid
+        """
+        key = self._normalize_path(file_path)
+
+        with self._lock:
+            if key not in self._cache:
+                if self._enable_stats:
+                    self._stats.misses += 1
+                return None
+
+            entry = self._cache[key]
+
+            # Validate entry
+            if not self._is_valid(entry, key):
+                del self._cache[key]
+                if self._enable_stats:
+                    self._stats.misses += 1
+                    self._stats.invalidations += 1
+                return None
+
+            # Cache hit
+            entry.touch()
+            if self._enable_stats:
+                self._stats.hits += 1
+
+            return entry.ast
+
+    def get_or_parse(
+        self,
+        file_path: Any,
+        parser: Any,
+        content: Optional[str] = None,
+    ) -> Any:
+        """
+        Get cached AST or parse the file if not cached.
+
+        Args:
+            file_path: Path to the .q file
+            parser: QuantumParser instance to use for parsing
+            content: Optional file content (if already read)
+
+        Returns:
+            ComponentNode (either cached or freshly parsed)
+        """
+        key = self._normalize_path(file_path)
+
+        with self._lock:
+            # Try cache first
+            cached = self.get(key)
+            if cached is not None:
+                return cached
+
+            # Need to parse
+            start_time = time.perf_counter()
+
+            # Read content if not provided
+            if content is None:
+                with open(key, 'r', encoding='utf-8') as f:
+                    content = f.read()
+
+            # Parse
+            ast = parser.parse(content)
+
+            parse_time = (time.perf_counter() - start_time) * 1000
+
+            # Get file info
+            mtime, size = self._get_file_info(key)
+            content_hash = self._compute_hash(content) if self._enable_hash else ""
+
+            # Evict if needed
+            self._evict_lru()
+
+            # Cache the result
+            entry = CacheEntry(
+                ast=ast,
+                mtime=mtime,
+                size=size,
+                hash=content_hash,
+            )
+            self._cache[key] = entry
+
+            # Update stats
+            if self._enable_stats:
+                self._stats.total_parse_time_ms += parse_time
+                self._stats.entries_count = len(self._cache)
+                self._stats.memory_estimate_kb += self._estimate_memory(ast)
+
+            return ast
+
+    def put(self, file_path: Any, ast: Any, content: Optional[str] = None):
+        """
+        Manually put an AST into the cache.
+
+        Args:
+            file_path: Path to the .q file
+            ast: The parsed ComponentNode
+            content: Optional file content for hash computation
+        """
+        key = self._normalize_path(file_path)
+
+        with self._lock:
+            mtime, size = self._get_file_info(key)
+            content_hash = ""
+            if self._enable_hash and content is not None:
+                content_hash = self._compute_hash(content)
+
+            self._evict_lru()
+
+            entry = CacheEntry(
+                ast=ast,
+                mtime=mtime,
+                size=size,
+                hash=content_hash,
+            )
+            self._cache[key] = entry
+
+            if self._enable_stats:
+                self._stats.entries_count = len(self._cache)
+
+    def invalidate(self, file_path: Optional[Any] = None):
+        """
+        Invalidate cache entries.
+
+        Args:
+            file_path: Specific file to invalidate, or None for all
+        """
+        with self._lock:
+            if file_path is None:
+                count = len(self._cache)
+                self._cache.clear()
+                self._dependencies.clear()
+                if self._enable_stats:
+                    self._stats.invalidations += count
+                    self._stats.entries_count = 0
+            else:
+                key = self._normalize_path(file_path)
+                if key in self._cache:
+                    del self._cache[key]
+                    if self._enable_stats:
+                        self._stats.invalidations += 1
+                        self._stats.entries_count = len(self._cache)
+
+                # Also invalidate dependents
+                self._invalidate_dependents(key)
+
+    def _invalidate_dependents(self, file_path: str):
+        """Invalidate all files that depend on this file"""
+        dependents = []
+        for path, deps in self._dependencies.items():
+            if file_path in deps:
+                dependents.append(path)
+
+        for dep_path in dependents:
+            if dep_path in self._cache:
+                del self._cache[dep_path]
+                if self._enable_stats:
+                    self._stats.invalidations += 1
+
+    def register_dependency(self, file_path: Any, depends_on: Any):
+        """
+        Register that file_path depends on depends_on.
+        Used for import tracking.
+
+        Args:
+            file_path: The file that has a dependency
+            depends_on: The file it depends on (imports)
+        """
+        key = self._normalize_path(file_path)
+        dep_key = self._normalize_path(depends_on)
+
+        with self._lock:
+            if key not in self._dependencies:
+                self._dependencies[key] = set()
+            self._dependencies[key].add(dep_key)
+
+    def preload(self, file_paths: List[Any], parser: Any):
+        """
+        Preload multiple files into the cache.
+
+        Args:
+            file_paths: List of paths to preload
+            parser: QuantumParser instance
+        """
+        for file_path in file_paths:
+            try:
+                self.get_or_parse(file_path, parser)
+            except Exception:
+                pass  # Ignore errors during preload
+
+    @property
+    def stats(self) -> CacheStats:
+        """Get cache statistics"""
+        with self._lock:
+            self._stats.entries_count = len(self._cache)
+            return self._stats
+
+    def reset_stats(self):
+        """Reset statistics counters"""
+        with self._lock:
+            entries = self._stats.entries_count
+            memory = self._stats.memory_estimate_kb
+            self._stats = CacheStats()
+            self._stats.entries_count = entries
+            self._stats.memory_estimate_kb = memory
+
+    def clear(self):
+        """Clear the entire cache"""
+        with self._lock:
+            self._cache.clear()
+            self._dependencies.clear()
+            if self._enable_stats:
+                self._stats.entries_count = 0
+                self._stats.memory_estimate_kb = 0
+
+    def cache_info(self) -> Dict[str, Any]:
+        """Get detailed cache information"""
+        with self._lock:
+            entries = []
+            for path, entry in self._cache.items():
+                entries.append({
+                    'path': path,
+                    'mtime': entry.mtime,
+                    'size': entry.size,
+                    'access_count': entry.access_count,
+                    'age_seconds': time.time() - entry.created_at,
+                })
+
+            return {
+                'max_entries': self._max_entries,
+                'current_entries': len(self._cache),
+                'hash_validation': self._enable_hash,
+                'entries': entries,
+            }
+
+
+# Global singleton instance
+_global_cache: Optional[ASTCache] = None
+_global_cache_lock = threading.Lock()
+
+
+def get_ast_cache(max_entries: int = 100) -> ASTCache:
+    """
+    Get the global AST cache instance (singleton pattern).
+
+    Args:
+        max_entries: Maximum cache size (only used on first call)
+
+    Returns:
+        The global ASTCache instance
+    """
+    global _global_cache
+
+    if _global_cache is None:
+        with _global_cache_lock:
+            if _global_cache is None:
+                _global_cache = ASTCache(max_entries=max_entries)
+
+    return _global_cache
+
+
+def invalidate_ast_cache(file_path: Optional[Any] = None):
+    """
+    Convenience function to invalidate the global AST cache.
+
+    Args:
+        file_path: Specific file to invalidate, or None for all
+    """
+    cache = get_ast_cache()
+    cache.invalidate(file_path)
+
+
+# Integration with hot reload
+class ASTCacheWatcher:
+    """
+    Watches for file changes and invalidates cache accordingly.
+    Integrates with the hot reload system.
+    """
+
+    def __init__(self, cache: Optional[ASTCache] = None):
+        self._cache = cache or get_ast_cache()
+        self._watching: Dict[str, float] = {}  # path -> last known mtime
+
+    def check_and_invalidate(self, file_path: Any) -> bool:
+        """
+        Check if a file has changed and invalidate if so.
+
+        Returns:
+            True if the file was invalidated
+        """
+        key = str(Path(file_path).resolve())
+
+        try:
+            current_mtime = os.stat(key).st_mtime
+        except OSError:
+            return False
+
+        if key in self._watching:
+            if current_mtime != self._watching[key]:
+                self._cache.invalidate(key)
+                self._watching[key] = current_mtime
+                return True
+        else:
+            self._watching[key] = current_mtime
+
+        return False
+
+    def on_file_changed(self, file_path: Any):
+        """
+        Callback for file change events (from hot reload).
+
+        Args:
+            file_path: Path to the changed file
+        """
+        self._cache.invalidate(file_path)