fal 1.2.1__py3-none-any.whl → 1.7.2__py3-none-any.whl

fal/cli/apps.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 from .parser import FalClientParser
@@ -6,7 +8,7 @@ if TYPE_CHECKING:
     from fal.sdk import AliasInfo, ApplicationInfo
 
 
-def _apps_table(apps: list["AliasInfo"]):
+def _apps_table(apps: list[AliasInfo]):
     from rich.table import Table
 
     table = Table()
@@ -56,7 +58,7 @@ def _add_list_parser(subparsers, parents):
     parser.set_defaults(func=_list)
 
 
-def _app_rev_table(revs: list["ApplicationInfo"]):
+def _app_rev_table(revs: list[ApplicationInfo]):
     from rich.table import Table
 
     table = Table()
@@ -219,7 +221,7 @@ def _runners(args):
             str(runner.in_flight_requests),
             (
                 "N/A (active)"
-                if not runner.expiration_countdown
+                if runner.expiration_countdown is None
                 else f"{runner.expiration_countdown}s"
             ),
             f"{runner.uptime} ({runner.uptime.total_seconds()}s)",

fal/cli/create.py

@@ -0,0 +1,26 @@
+PROJECT_TYPES = ["app"]
+
+
+def _create_project(project_type: str):
+    from cookiecutter.main import cookiecutter
+
+    cookiecutter("https://github.com/fal-ai/cookiecutter-fal.git")
+
+
+def add_parser(main_subparsers, parents):
+    apps_help = "Create fal applications."
+    parser = main_subparsers.add_parser(
+        "create",
+        description=apps_help,
+        help=apps_help,
+        parents=parents,
+    )
+
+    parser.add_argument(
+        metavar="project_type",
+        choices=PROJECT_TYPES,
+        help="Type of project to create.",
+        dest="project_type",
+    )
+
+    parser.set_defaults(func=_create_project)

fal/cli/deploy.py

@@ -1,7 +1,9 @@
 import argparse
 from collections import namedtuple
 from pathlib import Path
+from typing import Literal, Optional, Tuple, Union
 
+from ._utils import get_app_data_from_toml, is_app_name
 from .parser import FalClientParser, RefAction
 
 User = namedtuple("User", ["user_id", "username"])
@@ -60,11 +62,18 @@ def _get_user() -> User:
         raise FalServerlessError(f"Could not parse the user data: {e}")
 
 
-def _deploy(args):
+def _deploy_from_reference(
+    app_ref: Tuple[Optional[Union[Path, str]], ...],
+    app_name: str,
+    args,
+    auth: Optional[Literal["public", "shared", "private"]] = None,
+    deployment_strategy: Optional[Literal["recreate", "rolling"]] = None,
+    no_scale: bool = False,
+):
     from fal.api import FalServerlessError, FalServerlessHost
     from fal.utils import load_function_from
 
-    file_path, func_name = args.app_ref
+    file_path, func_name = app_ref
     if file_path is None:
         # Try to find a python file in the current directory
         options = list(Path(".").glob("*.py"))
@@ -77,22 +86,28 @@ def _deploy(args):
             )
 
         [file_path] = options
-        file_path = str(file_path)
+        file_path = str(file_path)  # type: ignore
 
     user = _get_user()
     host = FalServerlessHost(args.host)
-    isolated_function, app_name = load_function_from(
+    loaded = load_function_from(
         host,
-        file_path,
-        func_name,
+        file_path,  # type: ignore
+        func_name,  # type: ignore
     )
-    app_name = args.app_name or app_name
+    isolated_function = loaded.function
+    app_name = app_name or loaded.app_name  # type: ignore
+    app_auth = auth or loaded.app_auth or "private"
+    deployment_strategy = deployment_strategy or "recreate"
+
     app_id = host.register(
         func=isolated_function.func,
         options=isolated_function.options,
         application_name=app_name,
-        application_auth_mode=args.auth,
+        application_auth_mode=app_auth,
         metadata=isolated_function.options.host.get("metadata", {}),
+        deployment_strategy=deployment_strategy,
+        scale=not no_scale,
     )
 
     if app_id:
@@ -105,12 +120,47 @@ 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 _deploy(args):
+    # my-app
+    if is_app_name(args.app_ref):
+        # we do not allow --app-name and --auth to be used with app name
+        if args.app_name or args.auth:
+            raise ValueError("Cannot use --app-name or --auth with app name reference.")
+
+        app_name = args.app_ref[0]
+        app_ref, app_auth, app_deployment_strategy, app_no_scale = (
+            get_app_data_from_toml(app_name)
         )
+        file_path, func_name = RefAction.split_ref(app_ref)
+
+    # path/to/myfile.py::MyApp
+    else:
+        file_path, func_name = args.app_ref
+        app_name = args.app_name
+        app_auth = args.auth
+        app_deployment_strategy = args.strategy
+        app_no_scale = args.no_scale
+
+    _deploy_from_reference(
+        (file_path, func_name),
+        app_name,
+        args,
+        app_auth,
+        app_deployment_strategy,
+        app_no_scale,
+    )
 
 
 def add_parser(main_subparsers, parents):
@@ -121,14 +171,22 @@ def add_parser(main_subparsers, parents):
             raise argparse.ArgumentTypeError(f"{option} is not a auth option")
         return option
 
-    deploy_help = "Deploy a fal application."
+    deploy_help = (
+        "Deploy a fal application. "
+        "If no app reference is provided, the command will look for a "
+        "pyproject.toml file with a [tool.fal.apps] section and deploy the "
+        "application specified with the provided app name."
+    )
+
     epilog = (
         "Examples:\n"
         "  fal deploy\n"
         "  fal deploy path/to/myfile.py\n"
         "  fal deploy path/to/myfile.py::MyApp\n"
         "  fal deploy path/to/myfile.py::MyApp --app-name myapp --auth public\n"
+        "  fal deploy my-app\n"
     )
+
     parser = main_subparsers.add_parser(
         "deploy",
         parents=[*parents, FalClientParser(add_help=False)],
@@ -136,22 +194,45 @@ def add_parser(main_subparsers, parents):
         help=deploy_help,
         epilog=epilog,
     )
+
     parser.add_argument(
         "app_ref",
         nargs="?",
         action=RefAction,
         help=(
-            "Application reference. " "For example: `myfile.py::MyApp`, `myfile.py`."
+            "Application reference. Either a file path or a file path and a "
+            "function name separated by '::'. If no reference is provided, the "
+            "command will look for a pyproject.toml file with a [tool.fal.apps] "
+            "section and deploy the application specified with the provided app name.\n"
+            "File path example: path/to/myfile.py::MyApp\n"
+            "App name example: my-app\n"
         ),
     )
+
     parser.add_argument(
         "--app-name",
         help="Application name to deploy with.",
     )
+
     parser.add_argument(
         "--auth",
         type=valid_auth_option,
-        default="private",
         help="Application authentication mode (private, public).",
     )
+    parser.add_argument(
+        "--strategy",
+        choices=["recreate", "rolling"],
+        help="Deployment strategy.",
+        default="recreate",
+    )
+    parser.add_argument(
+        "--no-scale",
+        action="store_true",
+        help=(
+            "Use min_concurrency/max_concurrency/max_multiplexing from previous "
+            "deployment of application with this name, if exists. Otherwise will "
+            "use the values from the application code."
+        ),
+    )
+
     parser.set_defaults(func=_deploy)

fal/cli/main.py

@@ -6,7 +6,7 @@ from fal import __version__
 from fal.console import console
 from fal.console.icons import CROSS_ICON
 
-from . import apps, auth, deploy, doctor, keys, run, secrets
+from . import apps, auth, create, deploy, doctor, keys, run, runners, secrets
 from .debug import debugtools, get_debug_parser
 from .parser import FalParser, FalParserExit
 
@@ -31,7 +31,7 @@ def _get_main_parser() -> argparse.ArgumentParser:
         required=True,
     )
 
-    for cmd in [auth, apps, deploy, run, keys, secrets, doctor]:
+    for cmd in [auth, apps, deploy, run, keys, secrets, doctor, create, runners]:
         cmd.add_parser(subparsers, parents)
 
     return parser

fal/cli/parser.py

@@ -14,14 +14,18 @@ class RefAction(argparse.Action):
         kwargs.setdefault("default", (None, None))
         super().__init__(*args, **kwargs)
 
-    def __call__(self, parser, args, values, option_string=None):  # noqa: ARG002
-        if isinstance(values, tuple):
-            file_path, obj_path = values
-        elif values.find("::") > 1:
-            file_path, obj_path = values.split("::", 1)
-        else:
-            file_path, obj_path = values, None
+    @classmethod
+    def split_ref(cls, value):
+        if isinstance(value, tuple):
+            return value
+
+        if value.find("::") > 1:
+            return value.split("::", 1)
 
+        return value, None
+
+    def __call__(self, parser, args, values, option_string=None):  # noqa: ARG002
+        file_path, obj_path = self.split_ref(values)
         setattr(args, self.dest, (file_path, obj_path))
 
 

fal/cli/run.py

@@ -1,3 +1,4 @@
+from ._utils import get_app_data_from_toml, is_app_name
 from .parser import FalClientParser, RefAction
 
 
@@ -6,7 +7,17 @@ def _run(args):
     from fal.utils import load_function_from
 
     host = FalServerlessHost(args.host)
-    isolated_function, _ = load_function_from(host, *args.func_ref)
+
+    if is_app_name(args.func_ref):
+        app_name = args.func_ref[0]
+        app_ref, *_ = get_app_data_from_toml(app_name)
+        file_path, func_name = RefAction.split_ref(app_ref)
+    else:
+        file_path, func_name = args.func_ref
+
+    loaded = load_function_from(host, file_path, func_name)
+
+    isolated_function = loaded.function
     # let our exc handlers handle UserFunctionException
     isolated_function.reraise = False
     isolated_function()

fal/cli/runners.py

@@ -0,0 +1,44 @@
+from .parser import FalClientParser
+
+
+def _kill(args):
+    from fal.sdk import FalServerlessClient
+
+    client = FalServerlessClient(args.host)
+    with client.connect() as connection:
+        connection.kill_runner(args.id)
+
+
+def _add_kill_parser(subparsers, parents):
+    kill_help = "Kill a runner."
+    parser = subparsers.add_parser(
+        "kill",
+        description=kill_help,
+        help=kill_help,
+        parents=parents,
+    )
+    parser.add_argument(
+        "id",
+        help="Runner ID.",
+    )
+    parser.set_defaults(func=_kill)
+
+
+def add_parser(main_subparsers, parents):
+    runners_help = "Manage fal runners."
+    parser = main_subparsers.add_parser(
+        "runners",
+        description=runners_help,
+        help=runners_help,
+        parents=parents,
+        aliases=["machine"],  # backwards compatibility
+    )
+
+    subparsers = parser.add_subparsers(
+        title="Commands",
+        metavar="command",
+        required=True,
+        parser_class=FalClientParser,
+    )
+
+    _add_kill_parser(subparsers, parents)

fal/config.py

@@ -0,0 +1,23 @@
+import os
+
+import tomli
+
+
+class Config:
+    DEFAULT_CONFIG_PATH = "~/.fal/config.toml"
+    DEFAULT_PROFILE = "default"
+
+    def __init__(self):
+        self.config_path = os.path.expanduser(
+            os.getenv("FAL_CONFIG_PATH", self.DEFAULT_CONFIG_PATH)
+        )
+        self.profile = os.getenv("FAL_PROFILE", self.DEFAULT_PROFILE)
+
+        try:
+            with open(self.config_path, "rb") as file:
+                self.config = tomli.load(file)
+        except FileNotFoundError:
+            self.config = {}
+
+    def get(self, key):
+        return self.config.get(self.profile, {}).get(key)

fal/container.py

@@ -3,7 +3,7 @@ class ContainerImage:
     from a Dockerfile.
     """
 
-    _known_keys = {"dockerfile_str", "build_env", "build_args"}
+    _known_keys = {"dockerfile_str", "build_args", "registries", "builder"}
 
     @classmethod
     def from_dockerfile_str(cls, text: str, **kwargs):

fal/exceptions/__init__.py

@@ -1,3 +1,9 @@
 from __future__ import annotations
 
-from ._base import FalServerlessException  # noqa: F401
+from ._base import (
+    AppException,  # noqa: F401
+    FalServerlessException,  # noqa: F401
+    FieldException,  # noqa: F401
+    RequestCancelledException,  # noqa: F401
+)
+from ._cuda import CUDAOutOfMemoryException  # noqa: F401

fal/exceptions/_base.py

@@ -1,7 +1,58 @@
 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,
+                }
+            ]
+        )
+
+
+@dataclass
+class RequestCancelledException(FalServerlessException):
+    """Exception raised when the request is cancelled by the client."""
+
+    message: str = "Request cancelled by the client."

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/files.py

@@ -0,0 +1,81 @@
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, Optional, Sequence, Tuple, Union
+
+import tomli
+
+
+@lru_cache
+def _load_toml(path: Union[Path, str]) -> Dict[str, Any]:
+    with open(path, "rb") as f:
+        return tomli.load(f)
+
+
+@lru_cache
+def _cached_resolve(path: Path) -> Path:
+    return path.resolve()
+
+
+@lru_cache
+def find_project_root(srcs: Optional[Sequence[str]]) -> Tuple[Path, str]:
+    """Return a directory containing .git, or pyproject.toml.
+
+    That directory will be a common parent of all files and directories
+    passed in `srcs`.
+
+    If no directory in the tree contains a marker that would specify it's the
+    project root, the root of the file system is returned.
+
+    Returns a two-tuple with the first element as the project root path and
+    the second element as a string describing the method by which the
+    project root was discovered.
+    """
+    if not srcs:
+        srcs = [str(_cached_resolve(Path.cwd()))]
+
+    path_srcs = [_cached_resolve(Path(Path.cwd(), src)) for src in srcs]
+
+    # A list of lists of parents for each 'src'. 'src' is included as a
+    # "parent" of itself if it is a directory
+    src_parents = [
+        list(path.parents) + ([path] if path.is_dir() else []) for path in path_srcs
+    ]
+
+    common_base = max(
+        set.intersection(*(set(parents) for parents in src_parents)),
+        key=lambda path: path.parts,
+    )
+
+    for directory in (common_base, *common_base.parents):
+        if (directory / ".git").exists():
+            return directory, ".git directory"
+
+        if (directory / "pyproject.toml").is_file():
+            pyproject_toml = _load_toml(directory / "pyproject.toml")
+            if "fal" in pyproject_toml.get("tool", {}):
+                return directory, "pyproject.toml"
+
+    return directory, "file system root"
+
+
+def find_pyproject_toml(
+    path_search_start: Optional[Tuple[str, ...]] = None,
+) -> Optional[str]:
+    """Find the absolute filepath to a pyproject.toml if it exists"""
+    path_project_root, _ = find_project_root(path_search_start)
+    path_pyproject_toml = path_project_root / "pyproject.toml"
+
+    if path_pyproject_toml.is_file():
+        return str(path_pyproject_toml)
+
+
+def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
+    """Parse a pyproject toml file, pulling out relevant parts for fal.
+
+    If parsing fails, will raise a tomli.TOMLDecodeError.
+    """
+    pyproject_toml = _load_toml(path_config)
+    config: Dict[str, Any] = pyproject_toml.get("tool", {}).get("fal", {})
+    config = {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
+
+    return config