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

tetra_rp/cli/utils/skeleton_template/main.py

@@ -0,0 +1,44 @@
+import logging
+import os
+
+from fastapi import FastAPI
+
+from workers.cpu import cpu_router
+from workers.gpu import gpu_router
+
+logger = logging.getLogger(__name__)
+
+
+app = FastAPI(
+    title="Flash Application",
+    description="Distributed GPU and CPU computing with Runpod Flash",
+    version="0.1.0",
+)
+
+# Include routers
+app.include_router(gpu_router, prefix="/gpu", tags=["GPU Workers"])
+app.include_router(cpu_router, prefix="/cpu", tags=["CPU Workers"])
+
+
+@app.get("/")
+def home():
+    return {
+        "message": "Flash Application",
+        "docs": "/docs",
+        "endpoints": {"gpu_hello": "/gpu/hello", "cpu_hello": "/cpu/hello"},
+    }
+
+
+@app.get("/ping")
+def ping():
+    return {"status": "healthy"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    host = os.getenv("FLASH_HOST", "localhost")
+    port = int(os.getenv("FLASH_PORT", 8888))
+    logger.info(f"Starting Flash server on {host}:{port}")
+
+    uvicorn.run(app, host=host, port=port)

tetra_rp/cli/utils/skeleton_template/mothership.py

@@ -0,0 +1,55 @@
+"""
+Mothership Endpoint Configuration
+
+The mothership endpoint serves your FastAPI application routes.
+It is automatically deployed as a CPU-optimized load-balanced endpoint.
+
+To customize this configuration:
+- Modify worker scaling: change workersMin and workersMax values
+- Use GPU load balancer: import LiveLoadBalancer instead of CpuLiveLoadBalancer
+- Change endpoint name: update the 'name' parameter
+
+To disable mothership deployment:
+- Delete this file, or
+- Comment out the 'mothership' variable below
+
+Documentation: https://docs.runpod.io/flash/mothership
+"""
+
+from tetra_rp import CpuLiveLoadBalancer
+
+# Mothership endpoint configuration
+# This serves your FastAPI app routes from main.py
+mothership = CpuLiveLoadBalancer(
+    name="mothership",
+    workersMin=1,
+    workersMax=3,
+)
+
+# Examples of customization:
+
+# Increase scaling for high traffic
+# mothership = CpuLiveLoadBalancer(
+#     name="mothership",
+#     workersMin=2,
+#     workersMax=10,
+# )
+
+# Use GPU-based load balancer instead of CPU
+# (requires importing LiveLoadBalancer)
+# from tetra_rp import LiveLoadBalancer
+# mothership = LiveLoadBalancer(
+#     name="mothership",
+#     gpus=[GpuGroup.ANY],
+# )
+
+# Custom endpoint name
+# mothership = CpuLiveLoadBalancer(
+#     name="my-api-gateway",
+#     workersMin=1,
+#     workersMax=3,
+# )
+
+# To disable mothership:
+# - Delete this entire file, or
+# - Comment out the 'mothership' variable above

tetra_rp/cli/utils/skeleton_template/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{{project_name}}"
+version = "0.1.0"
+description = "Flash serverless application"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "tetra-rp",
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]

tetra_rp/cli/utils/skeleton_template/requirements.txt

@@ -0,0 +1 @@
+tetra_rp

tetra_rp/cli/utils/skeleton_template/workers/cpu/__init__.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from .endpoint import cpu_hello
+
+cpu_router = APIRouter()
+
+
+class MessageRequest(BaseModel):
+    """Request model for CPU worker."""
+
+    message: str = "Hello from CPU!"
+
+
+@cpu_router.post("/hello")
+async def hello(request: MessageRequest):
+    """Simple CPU worker endpoint."""
+    result = await cpu_hello({"message": request.message})
+    return result

tetra_rp/cli/utils/skeleton_template/workers/cpu/endpoint.py

@@ -0,0 +1,36 @@
+from tetra_rp import CpuLiveServerless, remote
+
+cpu_config = CpuLiveServerless(
+    name="cpu_worker",
+    workersMin=0,
+    workersMax=5,
+    idleTimeout=5,
+)
+
+
+@remote(resource_config=cpu_config)
+async def cpu_hello(input_data: dict) -> dict:
+    """Simple CPU worker example."""
+    import platform
+    from datetime import datetime
+
+    message = input_data.get("message", "Hello from CPU worker!")
+
+    return {
+        "status": "success",
+        "message": message,
+        "worker_type": "CPU",
+        "timestamp": datetime.now().isoformat(),
+        "platform": platform.system(),
+        "python_version": platform.python_version(),
+    }
+
+
+# Test locally with: python -m workers.cpu.endpoint
+if __name__ == "__main__":
+    import asyncio
+
+    test_payload = {"message": "Testing CPU worker"}
+    print(f"Testing CPU worker with payload: {test_payload}")
+    result = asyncio.run(cpu_hello(test_payload))
+    print(f"Result: {result}")

tetra_rp/cli/utils/skeleton_template/workers/gpu/__init__.py

@@ -0,0 +1,19 @@
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from .endpoint import gpu_hello
+
+gpu_router = APIRouter()
+
+
+class MessageRequest(BaseModel):
+    """Request model for GPU worker."""
+
+    message: str = "Hello from GPU!"
+
+
+@gpu_router.post("/hello")
+async def hello(request: MessageRequest):
+    """Simple GPU worker endpoint."""
+    result = await gpu_hello({"message": request.message})
+    return result

tetra_rp/cli/utils/skeleton_template/workers/gpu/endpoint.py

@@ -0,0 +1,61 @@
+from tetra_rp import GpuGroup, LiveServerless, remote
+
+gpu_config = LiveServerless(
+    name="gpu_worker",
+    gpus=[GpuGroup.ANY],
+    workersMin=0,
+    workersMax=3,
+    idleTimeout=5,
+)
+
+
+@remote(resource_config=gpu_config, dependencies=["torch"])
+async def gpu_hello(input_data: dict) -> dict:
+    """Simple GPU worker example with GPU detection."""
+    import platform
+    from datetime import datetime
+
+    try:
+        import torch
+
+        gpu_available = torch.cuda.is_available()
+        if gpu_available:
+            gpu_name = torch.cuda.get_device_name(0)
+            gpu_count = torch.cuda.device_count()
+            gpu_memory = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+        else:
+            gpu_name = "No GPU detected"
+            gpu_count = 0
+            gpu_memory = 0
+    except Exception as e:
+        gpu_available = False
+        gpu_name = f"Error detecting GPU: {str(e)}"
+        gpu_count = 0
+        gpu_memory = 0
+
+    message = input_data.get("message", "Hello from GPU worker!")
+
+    return {
+        "status": "success",
+        "message": message,
+        "worker_type": "GPU",
+        "gpu_info": {
+            "available": gpu_available,
+            "name": gpu_name,
+            "count": gpu_count,
+            "memory_gb": round(gpu_memory, 2) if gpu_memory else 0,
+        },
+        "timestamp": datetime.now().isoformat(),
+        "platform": platform.system(),
+        "python_version": platform.python_version(),
+    }
+
+
+# Test locally with: python -m workers.gpu.endpoint
+if __name__ == "__main__":
+    import asyncio
+
+    test_payload = {"message": "Testing GPU worker"}
+    print(f"Testing GPU worker with payload: {test_payload}")
+    result = asyncio.run(gpu_hello(test_payload))
+    print(f"Result: {result}")

tetra_rp/client.py

@@ -1,71 +1,174 @@
+import os
+import inspect
 import logging
 from functools import wraps
 from typing import List, Optional
-from .core.resources import ServerlessResource, ResourceManager, NetworkVolume
-from .stubs import stub_resource
 
+from .core.resources import LoadBalancerSlsResource, ResourceManager, ServerlessResource
+from .execute_class import create_remote_class
+from .stubs import stub_resource
 
 log = logging.getLogger(__name__)
 
 
 def remote(
     resource_config: ServerlessResource,
-    dependencies: List[str] = None,
-    system_dependencies: List[str] = None,
-    mount_volume: Optional[NetworkVolume] = None,
+    dependencies: Optional[List[str]] = None,
+    system_dependencies: Optional[List[str]] = None,
+    accelerate_downloads: bool = True,
+    local: bool = False,
+    method: Optional[str] = None,
+    path: Optional[str] = None,
     **extra,
 ):
     """
     Decorator to enable dynamic resource provisioning and dependency management for serverless functions.
 
     This decorator allows a function to be executed in a remote serverless environment, with support for
-    dynamic resource provisioning and installation of required dependencies.
+    dynamic resource provisioning and installation of required dependencies. It can also bypass remote
+    execution entirely for local testing.
+
+    Supports both sync and async function definitions:
+    - `def my_function(...)` - Regular synchronous function
+    - `async def my_function(...)` - Asynchronous function
+
+    In both cases, the decorated function returns an awaitable that must be called with `await`.
 
+    Args:
         resource_config (ServerlessResource): Configuration object specifying the serverless resource
-            to be provisioned or used.
+            to be provisioned or used. Not used when local=True.
         dependencies (List[str], optional): A list of pip package names to be installed in the remote
-            environment before executing the function. Defaults to None.
-        mount_volume (NetworkVolume, optional): Configuration for creating and mounting a network volume.
-            Should contain 'size', 'datacenter_id', and 'name' keys. Defaults to None.
+            environment before executing the function. Not used when local=True. Defaults to None.
+        system_dependencies (List[str], optional): A list of system packages to be installed in the remote
+            environment before executing the function. Not used when local=True. Defaults to None.
+        accelerate_downloads (bool, optional): Enable download acceleration for dependencies and models.
+            Only applies to remote execution. Defaults to True.
+        local (bool, optional): Execute function/class locally instead of provisioning remote servers.
+            Returns the unwrapped function/class for direct local execution. Users must ensure all required
+            dependencies are already installed in their local environment. Defaults to False.
+        method (str, optional): HTTP method for load-balanced endpoints (LoadBalancerSlsResource).
+            Required for LoadBalancerSlsResource: "GET", "POST", "PUT", "DELETE", "PATCH".
+            Ignored for queue-based endpoints. Defaults to None.
+        path (str, optional): HTTP path for load-balanced endpoints (LoadBalancerSlsResource).
+            Required for LoadBalancerSlsResource. Must start with "/". Example: "/api/process".
+            Ignored for queue-based endpoints. Defaults to None.
         extra (dict, optional): Additional parameters for the execution of the resource. Defaults to an empty dict.
 
     Returns:
-        Callable: A decorator that wraps the target function, enabling remote execution with the
-        specified resource configuration and dependencies.
+        Callable: A decorator that wraps the target function, enabling remote execution with the specified
+        resource configuration and dependencies, or returns the unwrapped function/class for local execution.
 
     Example:
     ```python
+        # Queue-based endpoint (recommended for reliability)
+        @remote(
+            resource_config=LiveServerless(name="gpu_worker"),
+            dependencies=["torch>=2.0.0"],
+        )
+        async def gpu_task(data: dict) -> dict:
+            import torch
+            # GPU processing here
+            return {"result": "processed"}
+
+        # Load-balanced endpoint (for low-latency APIs)
+        @remote(
+            resource_config=LoadBalancerSlsResource(name="api-service"),
+            method="POST",
+            path="/api/process",
+        )
+        async def api_endpoint(x: int, y: int) -> dict:
+            return {"result": x + y}
+
+        # Local execution (testing/development)
         @remote(
             resource_config=my_resource_config,
             dependencies=["numpy", "pandas"],
-            sync=True  # Optional, to run synchronously
+            local=True,
         )
-        async def my_function(data):
-            # Function logic here
+        async def my_test_function(data):
+            # Runs locally - dependencies must be pre-installed
             pass
     ```
     """
 
-    def decorator(func):
-        @wraps(func)
-        async def wrapper(*args, **kwargs):
-            # Create netowrk volume if mount_volume is provided
-            if mount_volume:
-                try:
-                    network_volume = await mount_volume.deploy()
-                    resource_config.networkVolumeId = network_volume.id
-                except Exception as e:
-                    log.error(f"Failed to create or mount network volume: {e}")
-                    raise
-
-            resource_manager = ResourceManager()
-            remote_resource = await resource_manager.get_or_deploy_resource(
-                resource_config
+    def decorator(func_or_class):
+        # Validate HTTP routing parameters for LoadBalancerSlsResource
+        is_lb_resource = isinstance(resource_config, LoadBalancerSlsResource)
+
+        if is_lb_resource:
+            if not method or not path:
+                raise ValueError(
+                    f"LoadBalancerSlsResource requires both 'method' and 'path' parameters. "
+                    f"Got method={method}, path={path}. "
+                    f"Example: @remote(resource_config, method='POST', path='/api/process')"
+                )
+            if not path.startswith("/"):
+                raise ValueError(f"path must start with '/'. Got: {path}")
+            valid_methods = {"GET", "POST", "PUT", "DELETE", "PATCH"}
+            if method not in valid_methods:
+                raise ValueError(
+                    f"method must be one of {valid_methods}. Got: {method}"
+                )
+        elif method or path:
+            log.warning(
+                f"HTTP routing parameters (method={method}, path={path}) are only used "
+                f"with LoadBalancerSlsResource, but resource_config is {type(resource_config).__name__}. "
+                f"They will be ignored."
+            )
+
+        # Store routing metadata for scanner and build system
+        routing_config = {
+            "resource_config": resource_config,
+            "method": method,
+            "path": path,
+            "dependencies": dependencies,
+            "system_dependencies": system_dependencies,
+        }
+
+        if os.getenv("RUNPOD_POD_ID") or os.getenv("RUNPOD_ENDPOINT_ID"):
+            # Worker mode when running on RunPod platform
+            func_or_class.__remote_config__ = routing_config
+            return func_or_class
+
+        # Local execution mode - execute without provisioning remote servers
+        if local:
+            func_or_class.__remote_config__ = routing_config
+            return func_or_class
+
+        # Remote execution mode
+        if inspect.isclass(func_or_class):
+            # Handle class decoration
+            wrapped_class = create_remote_class(
+                func_or_class,
+                resource_config,
+                dependencies,
+                system_dependencies,
+                accelerate_downloads,
+                extra,
             )
+            wrapped_class.__remote_config__ = routing_config
+            return wrapped_class
+        else:
+            # Handle function decoration
+            @wraps(func_or_class)
+            async def wrapper(*args, **kwargs):
+                resource_manager = ResourceManager()
+                remote_resource = await resource_manager.get_or_deploy_resource(
+                    resource_config
+                )
 
-            stub = stub_resource(remote_resource, **extra)
-            return await stub(func, dependencies, system_dependencies, *args, **kwargs)
+                stub = stub_resource(remote_resource, **extra)
+                return await stub(
+                    func_or_class,
+                    dependencies,
+                    system_dependencies,
+                    accelerate_downloads,
+                    *args,
+                    **kwargs,
+                )
 
-        return wrapper
+            # Store routing metadata on wrapper for scanner
+            wrapper.__remote_config__ = routing_config
+            return wrapper
 
     return decorator

tetra_rp/config.py

@@ -0,0 +1,29 @@
+"""Configuration management for tetra-rp CLI."""
+
+from pathlib import Path
+from typing import NamedTuple
+
+
+class TetraPaths(NamedTuple):
+    """Paths for tetra-rp configuration and data."""
+
+    tetra_dir: Path
+    config_file: Path
+    deployments_file: Path
+
+    def ensure_tetra_dir(self) -> None:
+        """Ensure the .tetra directory exists."""
+        self.tetra_dir.mkdir(exist_ok=True)
+
+
+def get_paths() -> TetraPaths:
+    """Get standardized paths for tetra-rp configuration."""
+    tetra_dir = Path.cwd() / ".tetra"
+    config_file = tetra_dir / "config.json"
+    deployments_file = tetra_dir / "deployments.json"
+
+    return TetraPaths(
+        tetra_dir=tetra_dir,
+        config_file=config_file,
+        deployments_file=deployments_file,
+    )