fal 1.2.4__tar.gz → 1.3.1__tar.gz

{fal-1.2.4 → fal-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fal
-Version: 1.2.4
+Version: 1.3.1
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8

{fal-1.2.4 → fal-1.3.1}/fal.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fal
-Version: 1.2.4
+Version: 1.3.1
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8

{fal-1.2.4 → fal-1.3.1}/fal.egg-info/SOURCES.txt

@@ -109,6 +109,7 @@ src/fal/console/icons.py
 src/fal/console/ux.py
 src/fal/exceptions/__init__.py
 src/fal/exceptions/_base.py
+src/fal/exceptions/_cuda.py
 src/fal/exceptions/auth.py
 src/fal/logging/__init__.py
 src/fal/logging/isolate.py

{fal-1.2.4 → fal-1.3.1}/src/fal/__main__.py

@@ -1,4 +1,6 @@
+import sys
+
 from .cli import main
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

{fal-1.2.4 → fal-1.3.1}/src/fal/_fal_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.2.4'
-__version_tuple__ = version_tuple = (1, 2, 4)
+__version__ = version = '1.3.1'
+__version_tuple__ = version_tuple = (1, 3, 1)

{fal-1.2.4 → fal-1.3.1}/src/fal/api.py

@@ -44,7 +44,13 @@ from typing_extensions import Concatenate, ParamSpec
 import fal.flags as flags
 from fal._serialization import include_modules_from, patch_pickle
 from fal.container import ContainerImage
-from fal.exceptions import FalServerlessException
+from fal.exceptions import (
+    AppException,
+    CUDAOutOfMemoryException,
+    FalServerlessException,
+    FieldException,
+)
+from fal.exceptions._cuda import _is_cuda_oom_exception
 from fal.logging.isolate import IsolateLogPrinter
 from fal.sdk import (
     FAL_SERVERLESS_DEFAULT_KEEP_ALIVE,
@@ -1002,13 +1008,39 @@ class BaseServable:
                 # If it's not a generic 404, just return the original message.
                 return JSONResponse({"detail": exc.detail}, 404)
 
+        @_app.exception_handler(AppException)
+        async def app_exception_handler(request: Request, exc: AppException):
+            return JSONResponse({"detail": exc.message}, exc.status_code)
+
+        @_app.exception_handler(FieldException)
+        async def field_exception_handler(request: Request, exc: FieldException):
+            return JSONResponse(exc.to_pydantic_format(), exc.status_code)
+
+        @_app.exception_handler(CUDAOutOfMemoryException)
+        async def cuda_out_of_memory_exception_handler(
+            request: Request, exc: CUDAOutOfMemoryException
+        ):
+            return JSONResponse({"detail": exc.message}, exc.status_code)
+
         @_app.exception_handler(Exception)
         async def traceback_logging_exception_handler(request: Request, exc: Exception):
-            print(
-                json.dumps(
-                    {"traceback": "".join(traceback.format_exception(exc)[::-1])}  # type: ignore
+            _, MINOR, *_ = sys.version_info
+
+            # traceback.format_exception() has a different signature in Python >=3.10
+            if MINOR >= 10:
+                formatted_exception = traceback.format_exception(exc)  # type: ignore
+            else:
+                formatted_exception = traceback.format_exception(
+                    type(exc), exc, exc.__traceback__
                 )
-            )
+
+            print(json.dumps({"traceback": "".join(formatted_exception[::-1])}))
+
+            if _is_cuda_oom_exception(exc):
+                return await cuda_out_of_memory_exception_handler(
+                    request, CUDAOutOfMemoryException()
+                )
+
             return JSONResponse({"detail": "Internal Server Error"}, 500)
 
         routes = self.collect_routes()

{fal-1.2.4 → fal-1.3.1}/src/fal/app.py

@@ -142,15 +142,14 @@ class AppClient:
         try:
             with httpx.Client() as client:
                 retries = 100
-                while retries:
-                    resp = client.get(info.url + "/health")
+                for _ in range(retries):
+                    resp = client.get(info.url + "/health", timeout=60)
 
                     if resp.is_success:
                         break
-                    elif resp.status_code != 500:
+                    elif resp.status_code not in (500, 404):
                         resp.raise_for_status()
                     time.sleep(0.1)
-                    retries -= 1
 
             client = cls(app_cls, info.url)
             yield client
@@ -206,6 +205,14 @@ class App(fal.api.BaseServable):
                 "Running apps through SDK is not implemented yet."
             )
 
+    @classmethod
+    def get_endpoints(cls) -> list[str]:
+        return [
+            signature.path
+            for _, endpoint in inspect.getmembers(cls, inspect.isfunction)
+            if (signature := getattr(endpoint, "route_signature", None))
+        ]
+
     def collect_routes(self) -> dict[RouteSignature, Callable[..., Any]]:
         return {
             signature: endpoint

{fal-1.2.4 → fal-1.3.1}/src/fal/cli/deploy.py

@@ -81,13 +81,14 @@ def _deploy(args):
 
     user = _get_user()
     host = FalServerlessHost(args.host)
-    isolated_function, app_name, app_auth = load_function_from(
+    loaded = load_function_from(
         host,
         file_path,
         func_name,
     )
-    app_name = args.app_name or app_name
-    app_auth = args.auth or app_auth or "private"
+    isolated_function = loaded.function
+    app_name = args.app_name or loaded.app_name
+    app_auth = args.auth or loaded.app_auth or "private"
     app_id = host.register(
         func=isolated_function.func,
         options=isolated_function.options,
@@ -106,12 +107,16 @@ def _deploy(args):
             "Registered a new revision for function "
             f"'{app_name}' (revision='{app_id}')."
         )
-        args.console.print(
-            f"Playground: https://fal.ai/models/{user.username}/{app_name}"
-        )
-        args.console.print(
-            f"Endpoint: https://{gateway_host}/{user.username}/{app_name}"
-        )
+        args.console.print("Playground:")
+        for endpoint in loaded.endpoints:
+            args.console.print(
+                f"\thttps://fal.ai/models/{user.username}/{app_name}{endpoint}"
+            )
+        args.console.print("Endpoints:")
+        for endpoint in loaded.endpoints:
+            args.console.print(
+                f"\thttps://{gateway_host}/{user.username}/{app_name}{endpoint}"
+            )
 
 
 def add_parser(main_subparsers, parents):

{fal-1.2.4 → fal-1.3.1}/src/fal/cli/run.py

@@ -6,7 +6,8 @@ def _run(args):
     from fal.utils import load_function_from
 
     host = FalServerlessHost(args.host)
-    isolated_function, _, _ = load_function_from(host, *args.func_ref)
+    loaded = load_function_from(host, *args.func_ref)
+    isolated_function = loaded.function
     # let our exc handlers handle UserFunctionException
     isolated_function.reraise = False
     isolated_function()

fal-1.3.1/src/fal/exceptions/__init__.py

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+from ._base import AppException, FalServerlessException, FieldException  # noqa: F401
+from ._cuda import CUDAOutOfMemoryException  # noqa: F401

fal-1.3.1/src/fal/exceptions/_base.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+class FalServerlessException(Exception):
+    """Base exception type for fal Serverless related flows and APIs."""
+
+    pass
+
+
+@dataclass
+class AppException(FalServerlessException):
+    """
+    Base exception class for application-specific errors.
+
+    Attributes:
+        message: A descriptive message explaining the error.
+        status_code: The HTTP status code associated with the error.
+    """
+
+    message: str
+    status_code: int
+
+
+@dataclass
+class FieldException(FalServerlessException):
+    """Exception raised for errors related to specific fields.
+
+    Attributes:
+        field: The field that caused the error.
+        message: A descriptive message explaining the error.
+        status_code: The HTTP status code associated with the error. Defaults to 422
+        type: The type of error. Defaults to "value_error"
+    """
+
+    field: str
+    message: str
+    status_code: int = 422
+    type: str = "value_error"
+
+    def to_pydantic_format(self) -> dict[str, list[dict]]:
+        return dict(
+            detail=[
+                {
+                    "loc": ["body", self.field],
+                    "msg": self.message,
+                    "type": self.type,
+                }
+            ]
+        )

fal-1.3.1/src/fal/exceptions/_cuda.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._base import AppException
+
+# PyTorch error message for out of memory
+_CUDA_OOM_MESSAGE = "CUDA error: out of memory"
+
+# Special status code for CUDA out of memory errors
+_CUDA_OOM_STATUS_CODE = 503
+
+
+@dataclass
+class CUDAOutOfMemoryException(AppException):
+    """Exception raised when a CUDA operation runs out of memory."""
+
+    message: str = _CUDA_OOM_MESSAGE
+    status_code: int = _CUDA_OOM_STATUS_CODE
+
+
+# based on https://github.com/Lightning-AI/pytorch-lightning/blob/37e04d075a5532c69b8ac7457795b4345cca30cc/src/lightning/pytorch/utilities/memory.py#L49
+def _is_cuda_oom_exception(exception: BaseException) -> bool:
+    return _is_cuda_out_of_memory(exception) or _is_cudnn_snafu(exception)
+
+
+# based on https://github.com/BlackHC/toma/blob/master/toma/torch_cuda_memory.py
+def _is_cuda_out_of_memory(exception: BaseException) -> bool:
+    return (
+        isinstance(exception, RuntimeError)
+        and len(exception.args) == 1
+        and "CUDA" in exception.args[0]
+        and "out of memory" in exception.args[0]
+    )
+
+
+# based on https://github.com/BlackHC/toma/blob/master/toma/torch_cuda_memory.py
+def _is_cudnn_snafu(exception: BaseException) -> bool:
+    # For/because of https://github.com/pytorch/pytorch/issues/4107
+    return (
+        isinstance(exception, RuntimeError)
+        and len(exception.args) == 1
+        and "cuDNN error: CUDNN_STATUS_NOT_SUPPORTED." in exception.args[0]
+    )

{fal-1.2.4 → fal-1.3.1}/src/fal/toolkit/file/file.py

@@ -149,14 +149,31 @@ class File(BaseModel):
         path: str | Path,
         content_type: Optional[str] = None,
         repository: FileRepository | RepositoryId = DEFAULT_REPOSITORY,
+        multipart: bool | None = None,
     ) -> File:
         file_path = Path(path)
         if not file_path.exists():
             raise FileNotFoundError(f"File {file_path} does not exist")
-        with open(file_path, "rb") as f:
-            data = f.read()
-        return File.from_bytes(
-            data, content_type, file_name=file_path.name, repository=repository
+
+        repo = (
+            repository
+            if isinstance(repository, FileRepository)
+            else get_builtin_repository(repository)
+        )
+
+        content_type = content_type or "application/octet-stream"
+
+        url, data = repo.save_file(
+            file_path,
+            content_type=content_type,
+            multipart=multipart,
+        )
+        return cls(
+            url=url,
+            file_data=data.data if data else None,
+            content_type=content_type,
+            file_name=file_path.name,
+            file_size=file_path.stat().st_size,
         )
 
     def as_bytes(self) -> bytes:

fal-1.3.1/src/fal/toolkit/file/providers/fal.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+import math
+import os
+from base64 import b64encode
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from fal.auth import key_credentials
+from fal.toolkit.exceptions import FileUploadException
+from fal.toolkit.file.types import FileData, FileRepository
+
+_FAL_CDN = "https://fal.media"
+
+
+@dataclass
+class ObjectLifecyclePreference:
+    expriation_duration_seconds: int
+
+
+GLOBAL_LIFECYCLE_PREFERENCE = ObjectLifecyclePreference(
+    expriation_duration_seconds=86400
+)
+
+
+@dataclass
+class FalFileRepositoryBase(FileRepository):
+    def _save(self, file: FileData, storage_type: str) -> str:
+        key_creds = key_credentials()
+        if not key_creds:
+            raise FileUploadException("FAL_KEY must be set")
+
+        key_id, key_secret = key_creds
+        headers = {
+            "Authorization": f"Key {key_id}:{key_secret}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        grpc_host = os.environ.get("FAL_HOST", "api.alpha.fal.ai")
+        rest_host = grpc_host.replace("api", "rest", 1)
+        storage_url = (
+            f"https://{rest_host}/storage/upload/initiate?storage_type={storage_type}"
+        )
+
+        try:
+            req = Request(
+                storage_url,
+                data=json.dumps(
+                    {
+                        "file_name": file.file_name,
+                        "content_type": file.content_type,
+                    }
+                ).encode(),
+                headers=headers,
+                method="POST",
+            )
+            with urlopen(req) as response:
+                result = json.load(response)
+
+            upload_url = result["upload_url"]
+            self._upload_file(upload_url, file)
+
+            return result["file_url"]
+        except HTTPError as e:
+            raise FileUploadException(
+                f"Error initiating upload. Status {e.status}: {e.reason}"
+            )
+
+    def _upload_file(self, upload_url: str, file: FileData):
+        req = Request(
+            upload_url,
+            method="PUT",
+            data=file.data,
+            headers={"Content-Type": file.content_type},
+        )
+
+        with urlopen(req):
+            return
+
+
+@dataclass
+class FalFileRepository(FalFileRepositoryBase):
+    def save(self, file: FileData) -> str:
+        return self._save(file, "gcs")
+
+
+class MultipartUpload:
+    MULTIPART_THRESHOLD = 100 * 1024 * 1024
+    MULTIPART_CHUNK_SIZE = 100 * 1024 * 1024
+    MULTIPART_MAX_CONCURRENCY = 10
+
+    def __init__(
+        self,
+        file_path: str | Path,
+        chunk_size: int | None = None,
+        content_type: str | None = None,
+        max_concurrency: int | None = None,
+    ) -> None:
+        self.file_path = file_path
+        self.chunk_size = chunk_size or self.MULTIPART_CHUNK_SIZE
+        self.content_type = content_type or "application/octet-stream"
+        self.max_concurrency = max_concurrency or self.MULTIPART_MAX_CONCURRENCY
+
+        self._parts: list[dict] = []
+
+        key_creds = key_credentials()
+        if not key_creds:
+            raise FileUploadException("FAL_KEY must be set")
+
+        key_id, key_secret = key_creds
+
+        self._auth_headers = {
+            "Authorization": f"Key {key_id}:{key_secret}",
+        }
+        grpc_host = os.environ.get("FAL_HOST", "api.alpha.fal.ai")
+        rest_host = grpc_host.replace("api", "rest", 1)
+        self._storage_upload_url = f"https://{rest_host}/storage/upload"
+
+    def create(self):
+        try:
+            req = Request(
+                f"{self._storage_upload_url}/initiate-multipart",
+                method="POST",
+                headers={
+                    **self._auth_headers,
+                    "Accept": "application/json",
+                    "Content-Type": "application/json",
+                },
+                data=json.dumps(
+                    {
+                        "file_name": os.path.basename(self.file_path),
+                        "content_type": self.content_type,
+                    }
+                ).encode(),
+            )
+            with urlopen(req) as response:
+                result = json.load(response)
+                self._upload_id = result["upload_id"]
+                self._file_url = result["file_url"]
+        except HTTPError as exc:
+            raise FileUploadException(
+                f"Error initiating upload. Status {exc.status}: {exc.reason}"
+            )
+
+    def _upload_part(self, url: str, part_number: int) -> dict:
+        with open(self.file_path, "rb") as f:
+            start = (part_number - 1) * self.chunk_size
+            f.seek(start)
+            data = f.read(self.chunk_size)
+            req = Request(
+                url,
+                method="PUT",
+                headers={"Content-Type": self.content_type},
+                data=data,
+            )
+
+            try:
+                with urlopen(req) as resp:
+                    return {
+                        "part_number": part_number,
+                        "etag": resp.headers["ETag"],
+                    }
+            except HTTPError as exc:
+                raise FileUploadException(
+                    f"Error uploading part {part_number} to {url}. "
+                    f"Status {exc.status}: {exc.reason}"
+                )
+
+    def upload(self) -> None:
+        import concurrent.futures
+
+        parts = math.ceil(os.path.getsize(self.file_path) / self.chunk_size)
+        with concurrent.futures.ThreadPoolExecutor(
+            max_workers=self.max_concurrency
+        ) as executor:
+            futures = []
+            for part_number in range(1, parts + 1):
+                upload_url = (
+                    f"{self._file_url}?upload_id={self._upload_id}"
+                    f"&part_number={part_number}"
+                )
+                futures.append(
+                    executor.submit(self._upload_part, upload_url, part_number)
+                )
+
+            for future in concurrent.futures.as_completed(futures):
+                entry = future.result()
+                self._parts.append(entry)
+
+    def complete(self):
+        url = f"{self._file_url}?upload_id={self._upload_id}"
+        try:
+            req = Request(
+                url,
+                method="POST",
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/json",
+                },
+                data=json.dumps({"parts": self._parts}).encode(),
+            )
+            with urlopen(req):
+                pass
+        except HTTPError as e:
+            raise FileUploadException(
+                f"Error completing upload {url}. Status {e.status}: {e.reason}"
+            )
+
+        return self._file_url
+
+
+@dataclass
+class FalFileRepositoryV2(FalFileRepositoryBase):
+    def save(self, file: FileData) -> str:
+        return self._save(file, "fal-cdn")
+
+    def _save_multipart(
+        self,
+        file_path: str | Path,
+        chunk_size: int | None = None,
+        content_type: str | None = None,
+        max_concurrency: int | None = None,
+    ) -> str:
+        multipart = MultipartUpload(
+            file_path,
+            chunk_size=chunk_size,
+            content_type=content_type,
+            max_concurrency=max_concurrency,
+        )
+        multipart.create()
+        multipart.upload()
+        return multipart.complete()
+
+    def save_file(
+        self,
+        file_path: str | Path,
+        content_type: str,
+        multipart: bool | None = None,
+        multipart_threshold: int | None = None,
+        multipart_chunk_size: int | None = None,
+        multipart_max_concurrency: int | None = None,
+    ) -> tuple[str, FileData | None]:
+        if multipart is None:
+            threshold = multipart_threshold or MultipartUpload.MULTIPART_THRESHOLD
+            multipart = os.path.getsize(file_path) > threshold
+
+        if multipart:
+            url = self._save_multipart(
+                file_path,
+                chunk_size=multipart_chunk_size,
+                content_type=content_type,
+                max_concurrency=multipart_max_concurrency,
+            )
+            data = None
+        else:
+            with open(file_path, "rb") as f:
+                data = FileData(
+                    f.read(),
+                    content_type=content_type,
+                    file_name=os.path.basename(file_path),
+                )
+            url = self.save(data)
+
+        return url, data
+
+
+@dataclass
+class InMemoryRepository(FileRepository):
+    def save(
+        self,
+        file: FileData,
+    ) -> str:
+        return f'data:{file.content_type};base64,{b64encode(file.data).decode("utf-8")}'
+
+
+@dataclass
+class FalCDNFileRepository(FileRepository):
+    def save(
+        self,
+        file: FileData,
+    ) -> str:
+        headers = {
+            **self.auth_headers,
+            "Accept": "application/json",
+            "Content-Type": file.content_type,
+            "X-Fal-File-Name": file.file_name,
+            "X-Fal-Object-Lifecycle-Preference": json.dumps(
+                dataclasses.asdict(GLOBAL_LIFECYCLE_PREFERENCE)
+            ),
+        }
+        url = os.getenv("FAL_CDN_HOST", _FAL_CDN) + "/files/upload"
+        request = Request(url, headers=headers, method="POST", data=file.data)
+        try:
+            with urlopen(request) as response:
+                result = json.load(response)
+        except HTTPError as e:
+            raise FileUploadException(
+                f"Error initiating upload. Status {e.status}: {e.reason}"
+            )
+
+        access_url = result["access_url"]
+        return access_url
+
+    @property
+    def auth_headers(self) -> dict[str, str]:
+        key_creds = key_credentials()
+        if not key_creds:
+            raise FileUploadException("FAL_KEY must be set")
+
+        key_id, key_secret = key_creds
+        return {
+            "Authorization": f"Bearer {key_id}:{key_secret}",
+            "User-Agent": "fal/0.1.0",
+        }

{fal-1.2.4 → fal-1.3.1}/src/fal/toolkit/file/types.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from mimetypes import guess_extension, guess_type
+from pathlib import Path
 from typing import Literal
 from uuid import uuid4
 
@@ -35,3 +36,20 @@ RepositoryId = Literal["fal", "fal_v2", "in_memory", "gcp_storage", "r2", "cdn"]
 class FileRepository:
     def save(self, data: FileData) -> str:
         raise NotImplementedError()
+
+    def save_file(
+        self,
+        file_path: str | Path,
+        content_type: str,
+        multipart: bool | None = None,
+        multipart_threshold: int | None = None,
+        multipart_chunk_size: int | None = None,
+        multipart_max_concurrency: int | None = None,
+    ) -> tuple[str, FileData | None]:
+        if multipart:
+            raise NotImplementedError()
+
+        with open(file_path, "rb") as fobj:
+            data = FileData(fobj.read(), content_type, Path(file_path).name)
+
+        return self.save(data), data