tetra-rp 0.17.1__py3-none-any.whl

tetra_rp/core/resources/template.py

@@ -0,0 +1,94 @@
+import requests
+from typing import Dict, List, Optional, Any
+from pydantic import BaseModel, model_validator
+from .base import BaseResource
+
+
+class KeyValuePair(BaseModel):
+    key: str
+    value: str
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, str]) -> "List[KeyValuePair]":
+        """
+        Create a list of KeyValuePair instances from a dictionary.
+        """
+        if not isinstance(data, dict):
+            raise ValueError("Input must be a dictionary.")
+
+        return [cls(key=key, value=value) for key, value in data.items()]
+
+
+class PodTemplate(BaseResource):
+    advancedStart: Optional[bool] = False
+    config: Optional[Dict[str, Any]] = {}
+    containerDiskInGb: Optional[int] = 64
+    containerRegistryAuthId: Optional[str] = ""
+    dockerArgs: Optional[str] = ""
+    env: Optional[List[KeyValuePair]] = []
+    imageName: Optional[str] = ""
+    name: Optional[str] = ""
+    ports: Optional[str] = ""
+    startScript: Optional[str] = ""
+
+    @model_validator(mode="after")
+    def sync_input_fields(self):
+        self.name = f"{self.name}__{self.resource_id}"
+        return self
+
+
+def update_system_dependencies(
+    template_id, token, system_dependencies, base_entry_cmd=None
+):
+    """
+    Updates Runpod template with system dependencies installed via apt-get,
+    and appends the app start command.
+
+    Args:
+        template_id (str): Runpod template ID.
+        token (str): Runpod API token.
+        system_dependencies (List[str]): List of apt packages to install.
+        base_entry_cmd (List[str]): The default command to run the app, e.g. ["uv", "run", "handler.py"]
+    Returns:
+        dict: API response JSON or error info.
+    """
+
+    # Compose apt-get install command if any packages specified
+    apt_cmd = ""
+    if system_dependencies:
+        joined_pkgs = " ".join(system_dependencies)
+        apt_cmd = f"apt-get update && apt-get install -y {joined_pkgs} && "
+
+    # Default start command if not provided
+    app_cmd = base_entry_cmd or ["uv", "run", "handler.py"]
+    app_cmd_str = " ".join(app_cmd)
+
+    # Full command to run in entrypoint shell
+    full_cmd = f"{apt_cmd}exec {app_cmd_str}"
+
+    payload = {
+        # other required fields like disk, env, image, etc, should be fetched or passed in real usage
+        "dockerEntrypoint": ["/bin/bash", "-c", full_cmd],
+        "dockerStartCmd": [],
+        # placeholder values, replace as needed or fetch from current template state
+        "containerDiskInGb": 50,
+        "containerRegistryAuthId": "",
+        "env": {},
+        "imageName": "your-image-name",
+        "isPublic": False,
+        "name": "your-template-name",
+        "ports": ["8888/http", "22/tcp"],
+        "readme": "",
+        "volumeInGb": 20,
+        "volumeMountPath": "/workspace",
+    }
+
+    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+
+    url = f"https://rest.runpod.io/v1/templates/{template_id}/update"
+    response = requests.post(url, json=payload, headers=headers)
+
+    try:
+        return response.json()
+    except Exception:
+        return {"error": "Invalid JSON response", "text": response.text}

tetra_rp/core/resources/utils.py

@@ -0,0 +1,50 @@
+from typing import Callable, Any, List, Union
+from pydantic import BaseModel
+from .gpu import GpuType, GpuTypeDetail
+from .serverless import ServerlessEndpoint
+
+
+"""
+Define the mapping for the methods and their return types
+Only include methods from runpod.*
+"""
+RUNPOD_TYPED_OPERATIONS = {
+    "get_gpus": List[GpuType],
+    "get_gpu": GpuTypeDetail,
+    "get_endpoints": List[ServerlessEndpoint],
+}
+
+
+def inquire(method: Callable, *args, **kwargs) -> Union[List[Any], Any]:
+    """
+    This function dynamically determines the return type of the provided method
+    based on a predefined mapping (`definitions`) and validates the result using
+    Pydantic models if applicable.
+
+    Refer to `RUNPOD_TYPED_OPERATIONS` for the mapping.
+
+    Example:
+    ----------
+    >>> import runpod
+    >>> inquire(runpod.get_gpus)
+    [
+        GpuType(id='NVIDIA A100 80GB', displayName='A100 80GB', memoryInGb=80),
+        GpuType(id='NVIDIA A100 40GB', displayName='A100 40GB', memoryInGb=40),
+        GpuType(id='NVIDIA A10', displayName='A10', memoryInGb=24)
+    ]
+    """
+    method_name = method.__name__
+    return_type = RUNPOD_TYPED_OPERATIONS.get(method_name)
+
+    raw_result = method(*args, **kwargs)
+
+    if hasattr(return_type, "__origin__") and return_type.__origin__ is list:
+        # List case
+        model_type = return_type.__args__[0]
+        if issubclass(model_type, BaseModel):
+            return [model_type.model_validate(item) for item in raw_result]
+    elif isinstance(return_type, type) and issubclass(return_type, BaseModel):
+        # Single object case
+        return return_type.model_validate(raw_result)
+    else:
+        raise ValueError(f"Unsupported return type for method '{method_name}'")

tetra_rp/core/utils/backoff.py

@@ -0,0 +1,43 @@
+import math
+import random
+from enum import Enum
+
+
+class BackoffStrategy(str, Enum):
+    EXPONENTIAL = "exponential"
+    LINEAR = "linear"
+    LOGARITHMIC = "logarithmic"
+
+
+def get_backoff_delay(
+    attempt: int,
+    base: float = 0.1,
+    max_seconds: float = 10.0,
+    jitter: float = 0.2,
+    strategy: BackoffStrategy = BackoffStrategy.EXPONENTIAL,
+) -> float:
+    """
+    Returns a backoff delay in seconds based on the number of attempts and strategy.
+
+    Parameters:
+    - attempt (int): The number of failed attempts or polls.
+    - base (float): The base delay time in seconds.
+    - max_seconds (float): The maximum delay.
+    - jitter (float): Random jitter as a fraction (e.g., 0.2 = ±20%). Prevent thundering herd
+    - strategy (BackoffStrategy): The backoff curve to apply.
+
+    Returns:
+    - float: The delay in seconds.
+    """
+    if strategy == BackoffStrategy.EXPONENTIAL:
+        delay = base * (2**attempt)
+    elif strategy == BackoffStrategy.LINEAR:
+        delay = base + (attempt * base)
+    elif strategy == BackoffStrategy.LOGARITHMIC:
+        delay = base * math.log2(attempt + 2)
+    else:
+        raise ValueError(f"Unsupported backoff strategy: {strategy}")
+
+    # Clamp to max and apply jitter
+    delay = min(delay, max_seconds)
+    return delay * random.uniform(1 - jitter, 1 + jitter)

tetra_rp/core/utils/constants.py

@@ -0,0 +1,10 @@
+"""
+Constants for utility modules and caching configurations.
+
+This module contains configurable constants used across the tetra-rp codebase
+to ensure consistency and easy maintenance.
+"""
+
+# Cache key generation constants
+HASH_TRUNCATE_LENGTH = 16  # Length to truncate hash values for cache keys
+UUID_FALLBACK_LENGTH = 8  # Length to truncate UUID values for fallback keys

tetra_rp/core/utils/file_lock.py

@@ -0,0 +1,260 @@
+"""
+Cross-platform file locking utilities.
+
+Provides unified file locking interface that works across Windows, macOS, and Linux.
+Uses platform-appropriate locking mechanisms:
+- Windows: msvcrt.locking()
+- Unix/Linux/macOS: fcntl.flock()
+- Fallback: Basic file existence checking (limited protection)
+"""
+
+import contextlib
+import logging
+import platform
+import time
+from pathlib import Path
+from typing import BinaryIO, Optional
+
+log = logging.getLogger(__name__)
+
+# Platform detection
+_IS_WINDOWS = platform.system() == "Windows"
+_IS_UNIX = platform.system() in ("Linux", "Darwin")
+
+# Initialize availability flags
+_WINDOWS_LOCKING_AVAILABLE = False
+_UNIX_LOCKING_AVAILABLE = False
+
+# Import platform-specific modules
+if _IS_WINDOWS:
+    try:
+        import msvcrt
+
+        _WINDOWS_LOCKING_AVAILABLE = True
+    except ImportError:
+        msvcrt = None
+        log.warning("msvcrt not available on Windows platform")
+
+if _IS_UNIX:
+    try:
+        import fcntl
+
+        _UNIX_LOCKING_AVAILABLE = True
+    except ImportError:
+        fcntl = None
+        log.warning("fcntl not available on Unix platform")
+
+
+class FileLockError(Exception):
+    """Exception raised when file locking operations fail."""
+
+    pass
+
+
+class FileLockTimeout(FileLockError):
+    """Exception raised when file locking times out."""
+
+    pass
+
+
+@contextlib.contextmanager
+def file_lock(
+    file_handle: BinaryIO,
+    exclusive: bool = True,
+    timeout: Optional[float] = 10.0,
+    retry_interval: float = 0.1,
+):
+    """
+    Cross-platform file locking context manager.
+
+    Args:
+        file_handle: Open file handle to lock
+        exclusive: True for exclusive lock, False for shared lock
+        timeout: Maximum seconds to wait for lock (None = no timeout)
+        retry_interval: Seconds to wait between lock attempts
+
+    Raises:
+        FileLockTimeout: If lock cannot be acquired within timeout
+        FileLockError: If locking operation fails
+
+    Usage:
+        with open("file.dat", "rb") as f:
+            with file_lock(f, exclusive=False):  # Shared read lock
+                data = f.read()
+
+        with open("file.dat", "wb") as f:
+            with file_lock(f, exclusive=True):   # Exclusive write lock
+                f.write(data)
+    """
+    lock_acquired = False
+    start_time = time.time()
+
+    try:
+        # Platform-specific locking
+        while not lock_acquired:
+            try:
+                if _IS_WINDOWS and _WINDOWS_LOCKING_AVAILABLE:
+                    _acquire_windows_lock(file_handle, exclusive)
+                elif _IS_UNIX and _UNIX_LOCKING_AVAILABLE:
+                    _acquire_unix_lock(file_handle, exclusive)
+                else:
+                    # Fallback - limited protection via file existence
+                    _acquire_fallback_lock(file_handle, exclusive, timeout)
+
+                lock_acquired = True
+                log.debug(f"File lock acquired (exclusive={exclusive})")
+
+            except (OSError, IOError, FileLockError) as e:
+                # Check timeout
+                if timeout is not None and (time.time() - start_time) >= timeout:
+                    raise FileLockTimeout(
+                        f"Could not acquire file lock within {timeout} seconds: {e}"
+                    ) from e
+
+                # Retry after interval
+                time.sleep(retry_interval)
+
+        # Lock acquired successfully
+        yield
+
+    finally:
+        # Release lock
+        if lock_acquired:
+            try:
+                if _IS_WINDOWS and _WINDOWS_LOCKING_AVAILABLE:
+                    _release_windows_lock(file_handle)
+                elif _IS_UNIX and _UNIX_LOCKING_AVAILABLE:
+                    _release_unix_lock(file_handle)
+                else:
+                    _release_fallback_lock(file_handle)
+
+                log.debug("File lock released")
+
+            except Exception as e:
+                log.error(f"Error releasing file lock: {e}")
+                # Don't raise - we're in cleanup
+
+
+def _acquire_windows_lock(file_handle: BinaryIO, exclusive: bool) -> None:
+    """Acquire Windows file lock using msvcrt.locking()."""
+    if not _WINDOWS_LOCKING_AVAILABLE:
+        raise FileLockError("Windows file locking not available (msvcrt missing)")
+
+    # Windows locking modes
+    if exclusive:
+        lock_mode = msvcrt.LK_NBLCK  # Non-blocking exclusive lock
+    else:
+        # Windows doesn't have shared locks in msvcrt
+        # Fall back to exclusive for compatibility
+        lock_mode = msvcrt.LK_NBLCK
+        log.debug("Windows: Using exclusive lock instead of shared (msvcrt limitation)")
+
+    try:
+        # Lock the entire file (position 0, length 1)
+        file_handle.seek(0)
+        msvcrt.locking(file_handle.fileno(), lock_mode, 1)
+    except OSError as e:
+        raise FileLockError(f"Failed to acquire Windows file lock: {e}") from e
+
+
+def _release_windows_lock(file_handle: BinaryIO) -> None:
+    """Release Windows file lock."""
+    if not _WINDOWS_LOCKING_AVAILABLE:
+        return
+
+    try:
+        file_handle.seek(0)
+        msvcrt.locking(file_handle.fileno(), msvcrt.LK_UNLCK, 1)
+    except OSError as e:
+        raise FileLockError(f"Failed to release Windows file lock: {e}") from e
+
+
+def _acquire_unix_lock(file_handle: BinaryIO, exclusive: bool) -> None:
+    """Acquire Unix file lock using fcntl.flock()."""
+    if not _UNIX_LOCKING_AVAILABLE:
+        raise FileLockError("Unix file locking not available (fcntl missing)")
+
+    # Unix locking modes
+    if exclusive:
+        lock_mode = fcntl.LOCK_EX | fcntl.LOCK_NB  # Non-blocking exclusive
+    else:
+        lock_mode = fcntl.LOCK_SH | fcntl.LOCK_NB  # Non-blocking shared
+
+    try:
+        fcntl.flock(file_handle.fileno(), lock_mode)
+    except (OSError, IOError) as e:
+        raise FileLockError(f"Failed to acquire Unix file lock: {e}") from e
+
+
+def _release_unix_lock(file_handle: BinaryIO) -> None:
+    """Release Unix file lock."""
+    if not _UNIX_LOCKING_AVAILABLE:
+        return
+
+    try:
+        fcntl.flock(file_handle.fileno(), fcntl.LOCK_UN)
+    except (OSError, IOError) as e:
+        raise FileLockError(f"Failed to release Unix file lock: {e}") from e
+
+
+def _acquire_fallback_lock(
+    file_handle: BinaryIO, exclusive: bool, timeout: Optional[float]
+) -> None:
+    """
+    Fallback locking using lock files.
+
+    This provides minimal protection but doesn't prevent all race conditions.
+    It's better than no locking but not as robust as OS-level file locks.
+    """
+    log.warning(
+        "Using fallback file locking - limited protection against race conditions"
+    )
+
+    # Create lock file based on the original file
+    file_path = (
+        Path(file_handle.name) if hasattr(file_handle, "name") else Path("unknown")
+    )
+    lock_file = file_path.with_suffix(file_path.suffix + ".lock")
+
+    start_time = time.time()
+
+    while True:
+        try:
+            # Try to create lock file atomically
+            lock_file.touch(mode=0o600, exist_ok=False)
+            log.debug(f"Fallback lock file created: {lock_file}")
+            return
+
+        except FileExistsError:
+            # Lock file exists, check timeout
+            if timeout is not None and (time.time() - start_time) >= timeout:
+                raise FileLockError(f"Fallback lock timeout: {lock_file} exists")
+
+            # Wait and retry
+            time.sleep(0.1)
+
+
+def _release_fallback_lock(file_handle: BinaryIO) -> None:
+    """Release fallback lock by removing lock file."""
+    try:
+        file_path = (
+            Path(file_handle.name) if hasattr(file_handle, "name") else Path("unknown")
+        )
+        lock_file = file_path.with_suffix(file_path.suffix + ".lock")
+
+        if lock_file.exists():
+            lock_file.unlink()
+            log.debug(f"Fallback lock file removed: {lock_file}")
+
+    except Exception as e:
+        log.error(f"Failed to remove fallback lock file: {e}")
+
+
+def get_platform_info() -> dict:
+    """Get information about current platform and available locking mechanisms."""
+    return {
+        "platform": platform.system(),
+        "windows_locking": _IS_WINDOWS and _WINDOWS_LOCKING_AVAILABLE,
+        "unix_locking": _IS_UNIX and _UNIX_LOCKING_AVAILABLE,
+        "fallback_only": not (_WINDOWS_LOCKING_AVAILABLE or _UNIX_LOCKING_AVAILABLE),
+    }

tetra_rp/core/utils/json.py

@@ -0,0 +1,33 @@
+from enum import Enum
+from typing import Any
+from pydantic import BaseModel
+
+
+def normalize_for_json(obj: Any) -> Any:
+    """
+    Recursively normalizes an object for JSON serialization.
+
+    This function handles various data types and ensures that objects
+    are converted into JSON-serializable formats. It supports the following:
+    - `BaseModel` instances: Converts them to dictionaries using `model_dump()`.
+    - Dictionaries: Recursively normalizes their values.
+    - Lists: Recursively normalizes their elements.
+    - Tuples: Recursively normalizes their elements and returns a tuple.
+    - Other types: Returns the object as is.
+
+    Args:
+        obj (Any): The object to normalize.
+
+    Returns:
+        Any: A JSON-serializable representation of the input object.
+    """
+    if isinstance(obj, BaseModel):
+        return normalize_for_json(obj.model_dump())
+    elif isinstance(obj, Enum):
+        return obj.value
+    elif isinstance(obj, dict):
+        return {k: normalize_for_json(v) for k, v in obj.items()}
+    elif isinstance(obj, (list, tuple)):
+        return type(obj)(normalize_for_json(i) for i in obj)
+    else:
+        return obj

tetra_rp/core/utils/lru_cache.py

@@ -0,0 +1,75 @@
+"""
+LRU Cache implementation using OrderedDict for memory-efficient caching with automatic eviction.
+
+This module provides a Least Recently Used (LRU) cache implementation that automatically
+manages memory by evicting the least recently used items when the cache exceeds its
+maximum size limit. It maintains O(1) access time and provides a dict-like interface.
+Thread-safe for concurrent access.
+"""
+
+import threading
+from collections import OrderedDict
+from typing import Any, Dict, Optional
+
+
+class LRUCache:
+    """
+    A Least Recently Used (LRU) cache implementation using OrderedDict.
+
+    Automatically evicts the least recently used items when the cache exceeds
+    the maximum size limit. Provides dict-like interface with O(1) operations.
+    Thread-safe for concurrent access using RLock.
+
+    Args:
+        max_size: Maximum number of items to store in cache (default: 1000)
+    """
+
+    def __init__(self, max_size: int = 1000):
+        self.max_size = max_size
+        self.cache = OrderedDict()
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Get item from cache, moving it to end (most recent) if found."""
+        with self._lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+                return self.cache[key]
+            return None
+
+    def set(self, key: str, value: Dict[str, Any]) -> None:
+        """Set item in cache, evicting oldest if at capacity."""
+        with self._lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+            else:
+                if len(self.cache) >= self.max_size:
+                    self.cache.popitem(last=False)  # Remove oldest
+            self.cache[key] = value
+
+    def clear(self) -> None:
+        """Clear all items from cache."""
+        with self._lock:
+            self.cache.clear()
+
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists in cache."""
+        with self._lock:
+            return key in self.cache
+
+    def __len__(self) -> int:
+        """Return number of items in cache."""
+        with self._lock:
+            return len(self.cache)
+
+    def __getitem__(self, key: str) -> Dict[str, Any]:
+        """Get item using bracket notation, moving to end if found."""
+        with self._lock:
+            if key in self.cache:
+                self.cache.move_to_end(key)
+                return self.cache[key]
+            raise KeyError(key)
+
+    def __setitem__(self, key: str, value: Dict[str, Any]) -> None:
+        """Set item using bracket notation."""
+        self.set(key, value)

tetra_rp/core/utils/singleton.py

@@ -0,0 +1,21 @@
+import threading
+
+
+class SingletonMixin:
+    """Thread-safe singleton mixin class.
+
+    Uses threading.Lock to ensure only one instance is created
+    per class, even under concurrent access.
+    """
+
+    _instances = {}
+    _lock = threading.Lock()
+
+    def __new__(cls, *args, **kwargs):
+        # Use double-checked locking pattern for performance
+        if cls not in cls._instances:
+            with cls._lock:
+                # Check again inside the lock (double-checked locking)
+                if cls not in cls._instances:
+                    cls._instances[cls] = super().__new__(cls)
+        return cls._instances[cls]

tetra_rp/core/validation.py

@@ -0,0 +1,44 @@
+"""Validation utilities for tetra_rp configuration.
+
+Provides validation functions for required environment variables and configuration.
+"""
+
+import os
+
+from tetra_rp.core.exceptions import RunpodAPIKeyError
+
+
+def validate_api_key() -> str:
+    """Validate that RUNPOD_API_KEY environment variable is set.
+
+    Returns:
+        The API key value if present.
+
+    Raises:
+        RunpodAPIKeyError: If RUNPOD_API_KEY is not set or is empty.
+    """
+    api_key = os.getenv("RUNPOD_API_KEY")
+
+    if not api_key or not api_key.strip():
+        raise RunpodAPIKeyError()
+
+    return api_key
+
+
+def validate_api_key_with_context(operation: str) -> str:
+    """Validate API key with additional context about the operation.
+
+    Args:
+        operation: Description of what operation requires the API key.
+
+    Returns:
+        The API key value if present.
+
+    Raises:
+        RunpodAPIKeyError: If RUNPOD_API_KEY is not set, with operation context.
+    """
+    try:
+        return validate_api_key()
+    except RunpodAPIKeyError as e:
+        context_message = f"Cannot {operation}: {str(e)}"
+        raise RunpodAPIKeyError(context_message) from e