tetra-rp 0.8.0__tar.gz → 0.10.0__tar.gz

{tetra_rp-0.8.0 → tetra_rp-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tetra_rp
-Version: 0.8.0
+Version: 0.10.0
 Summary: A Python library for distributed inference and serving of machine learning models
 Author-email: Marut Pandya <pandyamarut@gmail.com>, Patrick Rachford <prachford@icloud.com>, Dean Quinanola <dean.quinanola@runpod.io>
 License: MIT
@@ -11,7 +11,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: <3.14,>=3.9
 Description-Content-Type: text/markdown
 Requires-Dist: cloudpickle>=3.1.1
-Requires-Dist: runpod~=1.7.9
+Requires-Dist: runpod
 Requires-Dist: python-dotenv>=1.0.0
 
 # Tetra: Serverless computing for AI workloads
@@ -801,6 +801,6 @@ def fetch_data(url):
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 <p align="center">
-  <a href="https://github.com/yourusername/tetra">Tetra</a> •
+  <a href="https://github.com/runpod/tetra-rp">Tetra</a> •
   <a href="https://runpod.io">Runpod</a>
 </p>

{tetra_rp-0.8.0 → tetra_rp-0.10.0}/README.md

@@ -785,6 +785,6 @@ def fetch_data(url):
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 <p align="center">
-  <a href="https://github.com/yourusername/tetra">Tetra</a> •
+  <a href="https://github.com/runpod/tetra-rp">Tetra</a> •
   <a href="https://runpod.io">Runpod</a>
 </p>

tetra_rp-0.10.0/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "tetra_rp"
+version = "0.10.0"
+description = "A Python library for distributed inference and serving of machine learning models"
+authors = [
+    { name = "Marut Pandya", email = "pandyamarut@gmail.com" },
+    { name = "Patrick Rachford", email = "prachford@icloud.com" },
+    { name = "Dean Quinanola", email = "dean.quinanola@runpod.io" },
+]
+readme = "README.md"
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.9,<3.14"
+
+dependencies = [
+    "cloudpickle>=3.1.1",
+    "runpod",
+    "python-dotenv>=1.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.16.1",
+    "ruff>=0.11.9",
+]
+test = [
+    "pytest>=8.4.1",
+    "pytest-mock>=3.14.0",
+    "pytest-asyncio>=1.0.0",
+    "pytest-cov>=6.2.1",
+    "twine>=6.1.0",
+]
+
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+    "--cov=tetra_rp",
+    "--cov-report=term-missing",
+    "--cov-fail-under=35"
+]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests",
+    "slow: Slow tests"
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+    "ignore::pytest.PytestDeprecationWarning",
+    "ignore::pytest.PytestUnknownMarkWarning"
+]
+
+[tool.ruff]
+# Exclude tetra-examples directory since it's a separate repository
+exclude = [
+    "tetra-examples/",
+]
+
+[tool.mypy]
+# Basic configuration
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false  # Start lenient, can be stricter later
+disallow_incomplete_defs = false
+check_untyped_defs = true
+
+# Import discovery
+mypy_path = "."
+namespace_packages = true
+
+# Error output
+show_error_codes = true
+show_column_numbers = true
+pretty = true
+
+# Exclude directories
+exclude = [
+    "tetra-examples/",
+    "tests/",  # Start by excluding tests, can add later
+]
+
+# Per-module options
+[[tool.mypy.overrides]]
+module = [
+    "runpod.*",
+    "cloudpickle.*",
+]
+ignore_missing_imports = true

{tetra_rp-0.8.0 → tetra_rp-0.10.0}/src/tetra_rp/core/api/runpod.py

@@ -281,6 +281,30 @@ class RunpodRestClient:
 
         return result
 
+    async def list_network_volumes(self) -> Dict[str, Any]:
+        """
+        List all network volumes in Runpod.
+
+        Returns:
+            List of network volume objects or dict containing networkVolumes key.
+            The API may return either format depending on version.
+        """
+        log.debug("Listing network volumes")
+
+        result = await self._execute_rest(
+            "GET", f"{RUNPOD_REST_API_URL}/networkvolumes"
+        )
+
+        # Handle both list and dict responses
+        if isinstance(result, list):
+            volume_count = len(result)
+        else:
+            volume_count = len(result.get("networkVolumes", []))
+
+        log.debug(f"Listed {volume_count} network volumes")
+
+        return result
+
     async def close(self):
         """Close the HTTP session."""
         if self.session and not self.session.closed:

{tetra_rp-0.8.0 → tetra_rp-0.10.0}/src/tetra_rp/core/resources/live_serverless.py

@@ -3,9 +3,13 @@ import os
 from pydantic import model_validator
 from .serverless import ServerlessEndpoint
 
-
-TETRA_GPU_IMAGE = os.environ.get("TETRA_GPU_IMAGE", "runpod/tetra-rp:dev")
-TETRA_CPU_IMAGE = os.environ.get("TETRA_CPU_IMAGE", "runpod/tetra-rp-cpu:dev")
+TETRA_IMAGE_TAG = os.environ.get("TETRA_IMAGE_TAG", "latest")
+TETRA_GPU_IMAGE = os.environ.get(
+    "TETRA_GPU_IMAGE", f"runpod/tetra-rp:{TETRA_IMAGE_TAG}"
+)
+TETRA_CPU_IMAGE = os.environ.get(
+    "TETRA_CPU_IMAGE", f"runpod/tetra-rp-cpu:{TETRA_IMAGE_TAG}"
+)
 
 
 class LiveServerless(ServerlessEndpoint):

tetra_rp-0.10.0/src/tetra_rp/core/resources/network_volume.py

@@ -0,0 +1,152 @@
+import hashlib
+import logging
+from enum import Enum
+from typing import Optional
+
+from pydantic import (
+    Field,
+    field_serializer,
+)
+
+from ..api.runpod import RunpodRestClient
+from .base import DeployableResource
+from .constants import CONSOLE_BASE_URL
+
+log = logging.getLogger(__name__)
+
+
+class DataCenter(str, Enum):
+    """
+    Enum representing available data centers for network volumes.
+    #TODO: Add more data centers as needed. Lock this to the available data center.
+    """
+
+    EU_RO_1 = "EU-RO-1"
+
+
+class NetworkVolume(DeployableResource):
+    """
+    NetworkVolume resource for creating and managing Runpod network volumes.
+
+    This class handles the creation, deployment, and management of network volumes
+    that can be attached to serverless resources. Supports idempotent deployment
+    where multiple volumes with the same name will reuse existing volumes.
+
+    """
+
+    # Internal fixed value
+    dataCenterId: DataCenter = Field(default=DataCenter.EU_RO_1, frozen=True)
+
+    id: Optional[str] = Field(default=None)
+    name: Optional[str] = None
+    size: Optional[int] = Field(default=50, gt=0)  # Size in GB
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}:{self.id}"
+
+    @property
+    def resource_id(self) -> str:
+        """Unique resource ID based on name and datacenter for idempotent behavior."""
+        if self.name:
+            # Use name + datacenter for volumes with names to ensure idempotence
+            resource_type = self.__class__.__name__
+            config_key = f"{self.name}:{self.dataCenterId.value}"
+            hash_obj = hashlib.md5(f"{resource_type}:{config_key}".encode())
+            return f"{resource_type}_{hash_obj.hexdigest()}"
+        else:
+            # Fall back to default behavior for unnamed volumes
+            return super().resource_id
+
+    @field_serializer("dataCenterId")
+    def serialize_data_center_id(self, value: Optional[DataCenter]) -> Optional[str]:
+        """Convert DataCenter enum to string."""
+        return value.value if value is not None else None
+
+    @property
+    def is_created(self) -> bool:
+        "Returns True if the network volume already exists."
+        return self.id is not None
+
+    @property
+    def url(self) -> str:
+        """
+        Returns the URL for the network volume resource.
+        """
+        if not self.id:
+            raise ValueError("Network volume ID is not set")
+        return f"{CONSOLE_BASE_URL}/user/storage"
+
+    def is_deployed(self) -> bool:
+        """
+        Checks if the network volume resource is deployed and available.
+        """
+        return self.id is not None
+
+    def _normalize_volumes_response(self, volumes_response) -> list:
+        """Normalize API response to list format."""
+        if isinstance(volumes_response, list):
+            return volumes_response
+        return volumes_response.get("networkVolumes", [])
+
+    def _find_matching_volume(self, existing_volumes: list) -> Optional[dict]:
+        """Find existing volume matching name and datacenter."""
+        for volume_data in existing_volumes:
+            if (
+                volume_data.get("name") == self.name
+                and volume_data.get("dataCenterId") == self.dataCenterId.value
+            ):
+                return volume_data
+        return None
+
+    async def _find_existing_volume(self, client) -> Optional["NetworkVolume"]:
+        """Check for existing volume with same name and datacenter."""
+        if not self.name:
+            return None
+
+        log.debug(f"Checking for existing network volume with name: {self.name}")
+        volumes_response = await client.list_network_volumes()
+        existing_volumes = self._normalize_volumes_response(volumes_response)
+
+        if matching_volume := self._find_matching_volume(existing_volumes):
+            log.info(
+                f"Found existing network volume: {matching_volume.get('id')} with name '{self.name}'"
+            )
+            # Update our instance with the existing volume's ID
+            self.id = matching_volume.get("id")
+            return self
+
+        return None
+
+    async def _create_new_volume(self, client) -> "NetworkVolume":
+        """Create a new network volume."""
+        log.debug(f"Creating new network volume: {self.name or 'unnamed'}")
+        payload = self.model_dump(exclude_none=True)
+        result = await client.create_network_volume(payload)
+
+        if volume := self.__class__(**result):
+            return volume
+
+        raise ValueError("Deployment failed, no volume was created.")
+
+    async def deploy(self) -> "DeployableResource":
+        """
+        Deploys the network volume resource using the provided configuration.
+        Returns a DeployableResource object.
+        """
+        try:
+            # If the resource is already deployed, return it
+            if self.is_deployed():
+                log.debug(f"{self} exists")
+                return self
+
+            async with RunpodRestClient() as client:
+                # Check for existing volume first
+                if existing_volume := await self._find_existing_volume(client):
+                    return existing_volume
+
+                # No existing volume found, create a new one
+                return await self._create_new_volume(client)
+
+        except Exception as e:
+            log.error(f"{self} failed to deploy: {e}")
+            raise

{tetra_rp-0.8.0 → tetra_rp-0.10.0}/src/tetra_rp/core/resources/serverless.py

@@ -134,8 +134,12 @@ class ServerlessResource(DeployableResource):
         return value.value if value is not None else None
 
     @field_serializer("instanceIds")
-    def serialize_instance_ids(self, value: List[CpuInstanceType]) -> List[str]:
+    def serialize_instance_ids(
+        self, value: Optional[List[CpuInstanceType]]
+    ) -> Optional[List[str]]:
         """Convert CpuInstanceType enums to strings."""
+        if value is None:
+            return None
         return [item.value if hasattr(item, "value") else str(item) for item in value]
 
     @field_validator("gpus")
@@ -247,62 +251,6 @@ class ServerlessResource(DeployableResource):
             log.error(f"{self} failed to deploy: {e}")
             raise
 
-    async def is_ready_for_requests(self, give_up_threshold=10) -> bool:
-        """
-        Asynchronously checks if the serverless resource is ready to handle
-        requests by polling its health endpoint.
-
-        Args:
-            give_up_threshold (int, optional): The maximum number of polling
-            attempts before giving up and raising an error. Defaults to 10.
-
-        Returns:
-            bool: True if the serverless resource is ready for requests.
-
-        Raises:
-            ValueError: If the serverless resource is not deployed.
-            RuntimeError: If the health status is THROTTLED, UNHEALTHY, or UNKNOWN
-            after exceeding the give_up_threshold.
-        """
-        if not self.is_deployed():
-            raise ValueError("Serverless is not deployed")
-
-        log.debug(f"{self} | API /health")
-
-        current_pace = 0
-        attempt = 0
-
-        # Poll for health status
-        while True:
-            await asyncio.sleep(current_pace)
-
-            health = await asyncio.to_thread(self.endpoint.health)
-            health = ServerlessHealth(**health)
-
-            if health.is_ready:
-                return True
-            else:
-                # nothing changed, increase the gap
-                attempt += 1
-                indicator = "." * (attempt // 2) if attempt % 2 == 0 else ""
-                if indicator:
-                    log.info(f"{self} | {indicator}")
-
-                status = health.workers.status
-                if status in [
-                    Status.THROTTLED,
-                    Status.UNHEALTHY,
-                    Status.UNKNOWN,
-                ]:
-                    log.debug(f"{self} | Health {status.value}")
-
-                    if attempt >= give_up_threshold:
-                        # Give up
-                        raise RuntimeError(f"Health {status.value}")
-
-            # Adjust polling pace appropriately
-            current_pace = get_backoff_delay(attempt)
-
     async def run_sync(self, payload: Dict[str, Any]) -> "JobOutput":
         """
         Executes a serverless endpoint request with the payload.
@@ -319,9 +267,6 @@ class ServerlessResource(DeployableResource):
         try:
             # log.debug(f"[{log_group}] Payload: {payload}")
 
-            # Poll until requests can be sent
-            await self.is_ready_for_requests()
-
             log.info(f"{self} | API /run_sync")
             response = await asyncio.to_thread(_fetch_job)
             return JobOutput(**response)
@@ -346,9 +291,6 @@ class ServerlessResource(DeployableResource):
         try:
             # log.debug(f"[{self}] Payload: {payload}")
 
-            # Poll until requests can be sent
-            await self.is_ready_for_requests()
-
             # Create a job using the endpoint
             log.info(f"{self} | API /run")
             job = await asyncio.to_thread(self.endpoint.run, request_input=payload)
@@ -366,9 +308,8 @@ class ServerlessResource(DeployableResource):
             while True:
                 await asyncio.sleep(current_pace)
 
-                if await self.is_ready_for_requests():
-                    # Check job status
-                    job_status = await asyncio.to_thread(job.status)
+                # Check job status
+                job_status = await asyncio.to_thread(job.status)
 
                 if last_status == job_status:
                     # nothing changed, increase the gap

tetra_rp-0.10.0/src/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-0.10.0/src/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)