tetra-rp 0.6.0__py3-none-any.whl → 0.24.0__py3-none-any.whl

tetra_rp/core/deployment.py

@@ -0,0 +1,232 @@
+"""Background deployment orchestrator with progress tracking."""
+
+import asyncio
+import logging
+import threading
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import List
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from .resources.base import DeployableResource
+from .resources.resource_manager import ResourceManager
+
+log = logging.getLogger(__name__)
+console = Console()
+
+
+class DeploymentStatus(Enum):
+    """Status of a resource deployment."""
+
+    PENDING = "pending"
+    CHECKING = "checking"
+    CACHED = "cached"
+    DEPLOYING = "deploying"
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+@dataclass
+class DeploymentResult:
+    """Result of a resource deployment operation."""
+
+    resource: DeployableResource
+    status: DeploymentStatus
+    duration: float
+    error: str = ""
+    endpoint_id: str = ""
+
+
+class DeploymentOrchestrator:
+    """Orchestrates parallel resource deployment with progress tracking."""
+
+    def __init__(self, max_concurrent: int = 3):
+        """Initialize deployment orchestrator.
+
+        Args:
+            max_concurrent: Maximum number of concurrent deployments
+        """
+        self.max_concurrent = max_concurrent
+        self.manager = ResourceManager()
+        self.results: List[DeploymentResult] = []
+
+    def deploy_all_background(self, resources: List[DeployableResource]) -> None:
+        """Deploy all resources in background thread.
+
+        This method spawns a background thread to deploy resources without
+        blocking the main thread. Progress is logged to console.
+
+        Args:
+            resources: List of resources to deploy
+        """
+        if not resources:
+            console.print("[dim]No resources to deploy[/dim]")
+            return
+
+        def run_async_deployment():
+            """Run async deployment in background thread."""
+            try:
+                # Create new event loop for this thread
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+
+                # Run deployment silently in background
+                loop.run_until_complete(self.deploy_all(resources, show_progress=False))
+
+            except Exception as e:
+                log.error(f"Background deployment failed: {e}")
+            finally:
+                loop.close()
+
+        # Start background thread
+        thread = threading.Thread(target=run_async_deployment, daemon=True)
+        thread.start()
+
+        console.print(
+            f"[dim]Auto-provisioning {len(resources)} resource(s) in background...[/dim]"
+        )
+
+    async def deploy_all(
+        self, resources: List[DeployableResource], show_progress: bool = True
+    ) -> List[DeploymentResult]:
+        """Deploy all resources in parallel with progress tracking.
+
+        Args:
+            resources: List of resources to deploy
+            show_progress: Whether to show progress indicator and summary (default: True)
+
+        Returns:
+            List of deployment results
+        """
+        if not resources:
+            return []
+
+        # Create semaphore for concurrency control
+        semaphore = asyncio.Semaphore(self.max_concurrent)
+
+        # Create deployment tasks
+        deploy_tasks = [
+            self._deploy_with_semaphore(resource, semaphore) for resource in resources
+        ]
+
+        # Deploy with progress indication
+        if show_progress:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+            ) as progress:
+                task_id = progress.add_task(
+                    f"Provisioning {len(resources)} resource(s)...",
+                    total=None,
+                )
+
+                # Wait for all deployments
+                self.results = await asyncio.gather(
+                    *deploy_tasks, return_exceptions=False
+                )
+
+                progress.update(
+                    task_id,
+                    description=f"[green]✓ Provisioned {len(resources)} resource(s)",
+                )
+                progress.stop_task(task_id)
+
+            # Display summary
+            self._display_summary()
+        else:
+            # Silent deployment for background provisioning
+            self.results = await asyncio.gather(*deploy_tasks, return_exceptions=False)
+
+        return self.results
+
+    async def _deploy_with_semaphore(
+        self, resource: DeployableResource, semaphore: asyncio.Semaphore
+    ) -> DeploymentResult:
+        """Deploy single resource with semaphore control.
+
+        Args:
+            resource: Resource to deploy
+            semaphore: Semaphore for concurrency limiting
+
+        Returns:
+            Deployment result
+        """
+        start_time = datetime.now()
+        resource_name = getattr(resource, "name", "Unknown")
+
+        async with semaphore:
+            try:
+                # Quick check if already deployed
+                if resource.is_deployed():
+                    duration = (datetime.now() - start_time).total_seconds()
+                    return DeploymentResult(
+                        resource=resource,
+                        status=DeploymentStatus.CACHED,
+                        duration=duration,
+                        endpoint_id=getattr(resource, "id", "N/A"),
+                    )
+
+                # Deploy resource
+                deployed = await self.manager.get_or_deploy_resource(resource)
+                duration = (datetime.now() - start_time).total_seconds()
+
+                return DeploymentResult(
+                    resource=deployed,
+                    status=DeploymentStatus.SUCCESS,
+                    duration=duration,
+                    endpoint_id=getattr(deployed, "id", "N/A"),
+                )
+
+            except Exception as e:
+                duration = (datetime.now() - start_time).total_seconds()
+                log.error(f"Failed to deploy {resource_name}: {e}")
+
+                return DeploymentResult(
+                    resource=resource,
+                    status=DeploymentStatus.FAILED,
+                    duration=duration,
+                    error=str(e),
+                )
+
+    def _display_summary(self):
+        """Display deployment summary."""
+        if not self.results:
+            return
+
+        # Count statuses
+        cached = sum(1 for r in self.results if r.status == DeploymentStatus.CACHED)
+        deployed = sum(1 for r in self.results if r.status == DeploymentStatus.SUCCESS)
+        failed = sum(1 for r in self.results if r.status == DeploymentStatus.FAILED)
+        total_time = sum(r.duration for r in self.results)
+
+        # Build summary message
+        parts = []
+        if cached > 0:
+            parts.append(f"{cached} cached")
+        if deployed > 0:
+            parts.append(f"{deployed} deployed")
+        if failed > 0:
+            parts.append(f"{failed} failed")
+
+        status_text = ", ".join(parts)
+
+        console.print()
+        if failed > 0:
+            console.print(
+                f"[yellow]⚠[/yellow] Provisioning completed: {len(self.results)} resources "
+                f"({status_text}) in {total_time:.1f}s"
+            )
+            console.print(
+                "[yellow]Note:[/yellow] Failed resources will deploy on-demand when first called"
+            )
+        else:
+            console.print(
+                f"[green]✓[/green] Provisioning completed: {len(self.results)} resources "
+                f"({status_text}) in {total_time:.1f}s"
+            )
+
+        console.print()

tetra_rp/core/discovery.py

@@ -0,0 +1,425 @@
+"""Resource discovery for auto-provisioning during flash run startup."""
+
+import ast
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+from typing import Dict, List, Set
+
+from .resources.base import DeployableResource
+
+log = logging.getLogger(__name__)
+
+
+class ResourceDiscovery:
+    """Discovers DeployableResource instances by parsing @remote decorators."""
+
+    def __init__(self, entry_point: str, max_depth: int = 2):
+        """Initialize resource discovery.
+
+        Args:
+            entry_point: Path to entry point file (e.g., "main.py")
+            max_depth: Maximum depth for recursive module scanning
+        """
+        self.entry_point = Path(entry_point)
+        self.max_depth = max_depth
+        self._cache: Dict[str, List[DeployableResource]] = {}
+        self._scanned_modules: Set[str] = set()
+
+    def discover(self) -> List[DeployableResource]:
+        """Discover all DeployableResource instances in entry point and imports.
+
+        Returns:
+            List of discovered deployable resources
+        """
+        if str(self.entry_point) in self._cache:
+            return self._cache[str(self.entry_point)]
+
+        resources = []
+
+        try:
+            # Parse entry point to find @remote decorators
+            resource_var_names = self._find_resource_config_vars(self.entry_point)
+
+            # Import entry point module to resolve variables (if any found)
+            if resource_var_names:
+                module = self._import_module(self.entry_point)
+
+                if module:
+                    # Resolve variable names to actual DeployableResource objects
+                    for var_name in resource_var_names:
+                        resource = self._resolve_resource_variable(module, var_name)
+                        if resource:
+                            resources.append(resource)
+                            log.debug(
+                                f"Discovered resource: {var_name} -> {resource.__class__.__name__}"
+                            )
+                else:
+                    log.warning(f"Failed to import {self.entry_point}")
+
+            log.info(f"[Discovery] After entry point: {len(resources)} resource(s)")
+
+            # Recursively scan imported modules (static imports)
+            imported_resources = self._scan_imports(self.entry_point, depth=1)
+            resources.extend(imported_resources)
+
+            log.info(f"[Discovery] After static imports: {len(resources)} resource(s)")
+
+            # Fallback: Scan project directory for Python files with @remote decorators
+            # This handles dynamic imports (importlib.util) that AST parsing misses
+            if not resources:
+                log.debug(
+                    "No resources found via static imports, scanning project directory"
+                )
+                directory_resources = self._scan_project_directory()
+                resources.extend(directory_resources)
+                log.info(
+                    f"[Discovery] After directory scan: {len(resources)} resource(s)"
+                )
+
+            log.info(f"[Discovery] Total: {len(resources)} resource(s) discovered")
+            for res in resources:
+                res_name = getattr(res, "name", "Unknown")
+                res_type = res.__class__.__name__
+                log.info(f"[Discovery]   • {res_name} ({res_type})")
+
+            # Cache results
+            self._cache[str(self.entry_point)] = resources
+
+        except Exception as e:
+            log.error(f"Error discovering resources in {self.entry_point}: {e}")
+
+        return resources
+
+    def _find_resource_config_vars(self, file_path: Path) -> Set[str]:
+        """Find variable names used in @remote decorators via AST parsing.
+
+        Args:
+            file_path: Path to Python file to parse
+
+        Returns:
+            Set of variable names referenced in @remote decorators
+        """
+        var_names = set()
+
+        try:
+            tree = ast.parse(file_path.read_text(encoding="utf-8"))
+
+            for node in ast.walk(tree):
+                if isinstance(
+                    node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+                ):
+                    for decorator in node.decorator_list:
+                        if self._is_remote_decorator(decorator):
+                            # Extract resource_config variable name
+                            var_name = self._extract_resource_config_var(decorator)
+                            if var_name:
+                                var_names.add(var_name)
+
+        except Exception as e:
+            log.warning(f"Failed to parse {file_path}: {e}")
+
+        return var_names
+
+    def _is_remote_decorator(self, decorator: ast.expr) -> bool:
+        """Check if decorator is @remote.
+
+        Args:
+            decorator: AST decorator node
+
+        Returns:
+            True if decorator is @remote
+        """
+        if isinstance(decorator, ast.Call):
+            func_name = None
+            if isinstance(decorator.func, ast.Name):
+                func_name = decorator.func.id
+            elif isinstance(decorator.func, ast.Attribute):
+                func_name = decorator.func.attr
+
+            return func_name == "remote"
+
+        return False
+
+    def _extract_resource_config_var(self, decorator: ast.Call) -> str:
+        """Extract resource_config variable name from @remote decorator.
+
+        Handles both:
+        - @remote(resource_config=my_config)
+        - @remote(my_config) (positional argument)
+
+        Args:
+            decorator: AST Call node for @remote decorator
+
+        Returns:
+            Variable name or empty string
+        """
+        # Check keyword argument: resource_config=var_name
+        for keyword in decorator.keywords:
+            if keyword.arg == "resource_config":
+                if isinstance(keyword.value, ast.Name):
+                    return keyword.value.id
+
+        # Check positional argument: @remote(var_name)
+        if decorator.args and isinstance(decorator.args[0], ast.Name):
+            return decorator.args[0].id
+
+        return ""
+
+    def _import_module(self, file_path: Path):
+        """Import a Python module from file path.
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            Imported module or None if import fails
+        """
+        try:
+            # Create module spec
+            module_name = file_path.stem
+            spec = importlib.util.spec_from_file_location(module_name, file_path)
+
+            if not spec or not spec.loader:
+                return None
+
+            # Load module
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)
+
+            self._scanned_modules.add(module_name)
+
+            return module
+
+        except Exception as e:
+            log.warning(f"Failed to import {file_path}: {e}")
+            return None
+
+    def _resolve_resource_variable(self, module, var_name: str) -> DeployableResource:
+        """Resolve variable name to DeployableResource instance.
+
+        Args:
+            module: Imported module
+            var_name: Variable name to resolve
+
+        Returns:
+            DeployableResource instance or None
+        """
+        try:
+            obj = getattr(module, var_name, None)
+
+            if obj and isinstance(obj, DeployableResource):
+                return obj
+
+            log.warning(
+                f"Resource '{var_name}' failed to resolve to DeployableResource "
+                f"(found type: {type(obj).__name__}). "
+                f"Check that '{var_name}' is defined as a ServerlessResource or other DeployableResource type."
+            )
+
+        except Exception as e:
+            log.warning(f"Failed to resolve variable '{var_name}': {e}")
+
+        return None
+
+    def _scan_imports(self, file_path: Path, depth: int) -> List[DeployableResource]:
+        """Recursively scan imported modules for resources.
+
+        Args:
+            file_path: Path to Python file
+            depth: Current recursion depth
+
+        Returns:
+            List of discovered resources from imports
+        """
+        if depth > self.max_depth:
+            return []
+
+        resources = []
+
+        try:
+            tree = ast.parse(file_path.read_text(encoding="utf-8"))
+
+            # Find import statements
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Import):
+                    for alias in node.names:
+                        module_name = alias.name
+                        if module_name not in self._scanned_modules:
+                            imported_resources = self._scan_imported_module(
+                                module_name, depth
+                            )
+                            resources.extend(imported_resources)
+
+                elif isinstance(node, ast.ImportFrom):
+                    if node.module and node.module not in self._scanned_modules:
+                        imported_resources = self._scan_imported_module(
+                            node.module, depth
+                        )
+                        resources.extend(imported_resources)
+
+        except Exception as e:
+            log.debug(f"Failed to scan imports in {file_path}: {e}")
+
+        return resources
+
+    def _scan_imported_module(
+        self, module_name: str, depth: int
+    ) -> List[DeployableResource]:
+        """Scan an imported module for resources.
+
+        Args:
+            module_name: Name of module to scan
+            depth: Current recursion depth
+
+        Returns:
+            List of discovered resources
+        """
+        resources = []
+
+        try:
+            # Try to find module file
+            module_path = self._resolve_module_path(module_name)
+
+            if not module_path or not module_path.exists():
+                return []
+
+            # Mark as scanned to avoid cycles
+            self._scanned_modules.add(module_name)
+
+            # Find resources in this module
+            resource_vars = self._find_resource_config_vars(module_path)
+
+            if resource_vars:
+                # Import module and resolve variables
+                module = self._import_module(module_path)
+                if module:
+                    for var_name in resource_vars:
+                        resource = self._resolve_resource_variable(module, var_name)
+                        if resource:
+                            resources.append(resource)
+
+            # Recursively scan imports
+            imported_resources = self._scan_imports(module_path, depth + 1)
+            resources.extend(imported_resources)
+
+        except Exception as e:
+            log.debug(f"Failed to scan imported module '{module_name}': {e}")
+
+        return resources
+
+    def _resolve_module_path(self, module_name: str) -> Path:
+        """Resolve module name to file path.
+
+        Args:
+            module_name: Name of module (e.g., "workers.gpu")
+
+        Returns:
+            Path to module file or None
+        """
+        try:
+            # Handle relative imports from entry point directory
+            parts = module_name.split(".")
+            current_dir = self.entry_point.parent
+
+            # Try as relative path first
+            module_path = current_dir.joinpath(*parts)
+
+            # Check for .py file
+            if module_path.with_suffix(".py").exists():
+                return module_path.with_suffix(".py")
+
+            # Check for package (__init__.py)
+            if (module_path / "__init__.py").exists():
+                return module_path / "__init__.py"
+
+        except Exception as e:
+            log.debug(f"Failed to resolve module path for '{module_name}': {e}")
+
+        return None
+
+    def _scan_project_directory(self) -> List[DeployableResource]:
+        """Scan project directory for Python files with @remote decorators.
+
+        This is a fallback for projects that use dynamic imports (importlib.util)
+        which cannot be detected via static AST import scanning.
+
+        Returns:
+            List of discovered resources
+        """
+        resources = []
+        project_root = self.entry_point.parent
+
+        try:
+            # Find all Python files in project (excluding common ignore patterns)
+            python_files = []
+            for pattern in ["**/*.py"]:
+                for file_path in project_root.glob(pattern):
+                    # Skip entry point (already processed)
+                    if file_path == self.entry_point:
+                        continue
+
+                    # Skip common directories
+                    rel_path = str(file_path.relative_to(project_root))
+                    if any(
+                        skip in rel_path
+                        for skip in [
+                            ".venv/",
+                            "venv/",
+                            "__pycache__/",
+                            ".git/",
+                            "site-packages/",
+                            ".pytest_cache/",
+                            "build/",
+                            "dist/",
+                            ".tox/",
+                            "node_modules/",
+                            ".flash/",
+                        ]
+                    ):
+                        continue
+
+                    python_files.append(file_path)
+
+            log.debug(f"Scanning {len(python_files)} Python files in {project_root}")
+
+            # Check each file for @remote decorators
+            for file_path in python_files:
+                try:
+                    # Quick check: does file contain "@remote"?
+                    content = file_path.read_text(encoding="utf-8")
+                    if "@remote" not in content:
+                        continue
+
+                    # Find resource config variables via AST
+                    resource_vars = self._find_resource_config_vars(file_path)
+                    if not resource_vars:
+                        continue
+
+                    # Import module and resolve variables
+                    module = self._import_module(file_path)
+                    if module:
+                        for var_name in resource_vars:
+                            resource = self._resolve_resource_variable(module, var_name)
+                            if resource:
+                                resources.append(resource)
+                                log.debug(
+                                    f"Discovered resource in {file_path.relative_to(project_root)}: "
+                                    f"{var_name} -> {resource.__class__.__name__}"
+                                )
+
+                except Exception as e:
+                    log.debug(f"Failed to scan {file_path}: {e}")
+                    continue
+
+        except Exception as e:
+            log.warning(f"Failed to scan project directory: {e}")
+
+        return resources
+
+    def clear_cache(self):
+        """Clear discovery cache (for reload mode)."""
+        self._cache.clear()
+        self._scanned_modules.clear()

tetra_rp/core/exceptions.py

@@ -0,0 +1,50 @@
+"""Custom exceptions for tetra_rp.
+
+Provides clear, actionable error messages for common failure scenarios.
+"""
+
+
+class RunpodAPIKeyError(Exception):
+    """Raised when RUNPOD_API_KEY environment variable is missing or invalid.
+
+    This exception provides helpful guidance on how to obtain and configure
+    the API key required for remote execution and deployment features.
+    """
+
+    def __init__(self, message: str | None = None):
+        """Initialize with optional custom message.
+
+        Args:
+            message: Optional custom error message. If not provided, uses default.
+        """
+        if message is None:
+            message = self._default_message()
+        super().__init__(message)
+
+    @staticmethod
+    def _default_message() -> str:
+        """Generate default error message with setup instructions.
+
+        Returns:
+            Formatted error message with actionable steps.
+        """
+        return """RUNPOD_API_KEY environment variable is required but not set.
+
+To use Flash remote execution features, you need a Runpod API key.
+
+Get your API key:
+  https://docs.runpod.io/get-started/api-keys
+
+Set your API key using one of these methods:
+
+  1. Environment variable:
+     export RUNPOD_API_KEY=your_api_key_here
+
+  2. In your project's .env file:
+     echo "RUNPOD_API_KEY=your_api_key_here" >> .env
+
+  3. In your shell profile (~/.bashrc, ~/.zshrc):
+     echo 'export RUNPOD_API_KEY=your_api_key_here' >> ~/.bashrc
+
+Note: If you created a .env file, make sure it's in your current directory
+or project root where Flash can find it."""