fal 0.11.2__py3-none-any.whl → 0.11.4__py3-none-any.whl

fal/__init__.py

@@ -6,6 +6,7 @@ from fal import apps
 from fal.api import FalServerlessHost, LocalHost, cached
 from fal.api import function
 from fal.api import function as isolated
+from fal.app import App, endpoint, wrap_app
 from fal.sdk import FalServerlessKeyCredentials
 from fal.sync import sync_dir
 
@@ -15,35 +16,8 @@ serverless = FalServerlessHost()
 # DEPRECATED - use serverless instead
 cloud = FalServerlessHost()
 
-DBT_FAL_IMPORT_NOTICE = """
-The dbt tool `fal` and `dbt-fal` adapter have been merged into a single tool.
-Please import from the `fal.dbt` module instead.
-Running `pip install dbt-fal` will install the new tool and the adapter alongside.
-Then import from the `fal.dbt` module like
-
-    from fal.dbt import {name}
-
-"""
-
-
-# Avoid printing on non-direct imports
-def __getattr__(name: str):
-    if name in (
-        "NodeStatus",
-        "FalDbt",
-        "DbtModel",
-        "DbtSource",
-        "DbtTest",
-        "DbtGenericTest",
-        "DbtSingularTest",
-        "Context",
-        "CurrentModel",
-    ):
-        raise ImportError(DBT_FAL_IMPORT_NOTICE.format(name=name))
-
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
 
+# NOTE: This makes `import fal.dbt` import the `dbt-fal` module and `import fal` import the `fal` module
 # NOTE: taken from dbt-core: https://github.com/dbt-labs/dbt-core/blob/ac539fd5cf325cfb5315339077d03399d575f570/core/dbt/adapters/__init__.py#L1-L7
 # N.B.
 # This will add to the package’s __path__ all subdirectories of directories on sys.path named after the package which effectively combines both modules into a single namespace (dbt.adapters)

fal/api.py

@@ -76,9 +76,7 @@ class Host(Generic[ArgsT, ReturnT]):
     is executed."""
 
     _SUPPORTED_KEYS: ClassVar[frozenset[str]] = frozenset()
-    _GATEWAY_KEYS: ClassVar[frozenset[str]] = frozenset(
-        {"serve", "exposed_port", "max_concurrency"}
-    )
+    _GATEWAY_KEYS: ClassVar[frozenset[str]] = frozenset({"serve", "exposed_port"})
 
     def __post_init__(self):
         assert not self._SUPPORTED_KEYS.intersection(
@@ -118,7 +116,6 @@ class Host(Generic[ArgsT, ReturnT]):
         self,
         func: Callable[ArgsT, ReturnT],
         options: Options,
-        max_concurrency: int | None = None,
         application_name: str | None = None,
         application_auth_mode: Literal["public", "shared", "private"] | None = None,
         metadata: dict[str, Any] | None = None,
@@ -311,6 +308,7 @@ class FalServerlessHost(Host):
         {
             "machine_type",
             "keep_alive",
+            "max_concurrency",
             "max_multiplexing",
             "setup_function",
             "metadata",
@@ -341,7 +339,6 @@ class FalServerlessHost(Host):
         self,
         func: Callable[ArgsT, ReturnT],
         options: Options,
-        max_concurrency: int | None = None,
         application_name: str | None = None,
         application_auth_mode: Literal["public", "shared", "private"] | None = None,
         metadata: dict[str, Any] | None = None,
@@ -354,9 +351,8 @@ class FalServerlessHost(Host):
             "machine_type", FAL_SERVERLESS_DEFAULT_MACHINE_TYPE
         )
         keep_alive = options.host.get("keep_alive", FAL_SERVERLESS_DEFAULT_KEEP_ALIVE)
-        max_multiplexing = options.host.get(
-            "max_multiplexing", FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING
-        )
+        max_concurrency = options.host.get("max_concurrency")
+        max_multiplexing = options.host.get("max_multiplexing")
         base_image = options.host.get("_base_image", None)
         scheduler = options.host.get("_scheduler", None)
         scheduler_options = options.host.get("_scheduler_options", None)
@@ -370,6 +366,7 @@ class FalServerlessHost(Host):
             scheduler=scheduler,
             scheduler_options=scheduler_options,
             max_multiplexing=max_multiplexing,
+            max_concurrency=max_concurrency,
         )
 
         partial_func = _prepare_partial_func(func)
@@ -394,7 +391,6 @@ class FalServerlessHost(Host):
             application_name=application_name,
             application_auth_mode=application_auth_mode,
             machine_requirements=machine_requirements,
-            max_concurrency=max_concurrency,
             metadata=metadata,
         ):
             for log in partial_result.logs:
@@ -419,9 +415,8 @@ class FalServerlessHost(Host):
             "machine_type", FAL_SERVERLESS_DEFAULT_MACHINE_TYPE
         )
         keep_alive = options.host.get("keep_alive", FAL_SERVERLESS_DEFAULT_KEEP_ALIVE)
-        max_multiplexing = options.host.get(
-            "max_multiplexing", FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING
-        )
+        max_concurrency = options.host.get("max_concurrency")
+        max_multiplexing = options.host.get("max_multiplexing")
         base_image = options.host.get("_base_image", None)
         scheduler = options.host.get("_scheduler", None)
         scheduler_options = options.host.get("_scheduler_options", None)
@@ -436,6 +431,7 @@ class FalServerlessHost(Host):
             scheduler=scheduler,
             scheduler_options=scheduler_options,
             max_multiplexing=max_multiplexing,
+            max_concurrency=max_concurrency,
         )
 
         return_value = _UNSET
@@ -556,6 +552,7 @@ def function(
     exposed_port: int | None = None,
     max_concurrency: int | None = None,
     # FalServerlessHost options
+    metadata: dict[str, Any] | None = None,
     machine_type: str = FAL_SERVERLESS_DEFAULT_MACHINE_TYPE,
     keep_alive: int = FAL_SERVERLESS_DEFAULT_KEEP_ALIVE,
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
@@ -580,6 +577,7 @@ def function(
     exposed_port: int | None = None,
     max_concurrency: int | None = None,
     # FalServerlessHost options
+    metadata: dict[str, Any] | None = None,
     machine_type: str = FAL_SERVERLESS_DEFAULT_MACHINE_TYPE,
     keep_alive: int = FAL_SERVERLESS_DEFAULT_KEEP_ALIVE,
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
@@ -656,6 +654,7 @@ def function(
     exposed_port: int | None = None,
     max_concurrency: int | None = None,
     # FalServerlessHost options
+    metadata: dict[str, Any] | None = None,
     machine_type: str = FAL_SERVERLESS_DEFAULT_MACHINE_TYPE,
     keep_alive: int = FAL_SERVERLESS_DEFAULT_KEEP_ALIVE,
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
@@ -685,6 +684,7 @@ def function(
     exposed_port: int | None = None,
     max_concurrency: int | None = None,
     # FalServerlessHost options
+    metadata: dict[str, Any] | None = None,
     machine_type: str = FAL_SERVERLESS_DEFAULT_MACHINE_TYPE,
     keep_alive: int = FAL_SERVERLESS_DEFAULT_KEEP_ALIVE,
     max_multiplexing: int = FAL_SERVERLESS_DEFAULT_MAX_MULTIPLEXING,
@@ -792,7 +792,7 @@ class ServeWrapper:
             if "properties" in schema:
                 mark_order(schema, "properties")
 
-        for key in spec["components"].get("schemas") or {}:
+        for key in spec.get("components", {}).get("schemas") or {}:
             order_schema_object(spec["components"]["schemas"][key])
 
         return spec

fal/app.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import inspect
+import os
+import fal.api
+from fal.toolkit import mainify
+from fastapi import FastAPI
+from typing import Any, NamedTuple, Callable, TypeVar, ClassVar
+from fal.logging import get_logger
+
+EndpointT = TypeVar("EndpointT", bound=Callable[..., Any])
+logger = get_logger(__name__)
+
+
+def wrap_app(cls: type[App], **kwargs) -> fal.api.IsolatedFunction:
+    def initialize_and_serve():
+        app = cls()
+        app.serve()
+
+    try:
+        app = cls(_allow_init=True)
+        metadata = app.openapi()
+    except Exception as exc:
+        logger.warning("Failed to build OpenAPI specification for %s", cls.__name__)
+        metadata = {}
+
+    wrapper = fal.api.function(
+        "virtualenv",
+        requirements=cls.requirements,
+        machine_type=cls.machine_type,
+        **cls.host_kwargs,
+        **kwargs,
+        metadata=metadata,
+        serve=True,
+    )
+    return wrapper(initialize_and_serve).on(
+        serve=False,
+        exposed_port=8080,
+    )
+
+
+@mainify
+class RouteSignature(NamedTuple):
+    path: str
+
+
+@mainify
+class App:
+    requirements: ClassVar[list[str]] = []
+    machine_type: ClassVar[str] = "S"
+    host_kwargs: ClassVar[dict[str, Any]] = {}
+
+    def __init_subclass__(cls, **kwargs):
+        cls.host_kwargs = kwargs
+
+        if cls.__init__ is not App.__init__:
+            raise ValueError(
+                "App classes should not override __init__ directly. "
+                "Use setup() instead."
+            )
+
+    def __init__(self, *, _allow_init: bool = False):
+        if not _allow_init and not os.getenv("IS_ISOLATE_AGENT"):
+            raise NotImplementedError(
+                "Running apps through SDK is not implemented yet."
+            )
+
+    def setup(self):
+        """Setup the application before serving."""
+
+    def serve(self) -> None:
+        import uvicorn
+
+        app = self._build_app()
+        self.setup()
+        uvicorn.run(app, host="0.0.0.0", port=8080)
+
+    def _build_app(self) -> FastAPI:
+        from fastapi import FastAPI
+        from fastapi.middleware.cors import CORSMiddleware
+
+        _app = FastAPI()
+
+        _app.add_middleware(
+            CORSMiddleware,
+            allow_credentials=True,
+            allow_headers=("*"),
+            allow_methods=("*"),
+            allow_origins=("*"),
+        )
+
+        routes: dict[RouteSignature, Callable[..., Any]] = {
+            signature: endpoint
+            for _, endpoint in inspect.getmembers(self, inspect.ismethod)
+            if (signature := getattr(endpoint, "route_signature", None))
+        }
+        if not routes:
+            raise ValueError("An application must have at least one route!")
+
+        for signature, endpoint in routes.items():
+            _app.add_api_route(
+                signature.path,
+                endpoint,
+                name=endpoint.__name__,
+                methods=["POST"],
+            )
+
+        return _app
+
+    def openapi(self) -> dict[str, Any]:
+        """
+        Build the OpenAPI specification for the served function.
+        Attach needed metadata for a better integration to fal.
+        """
+        app = self._build_app()
+        spec = app.openapi()
+        self._mark_order_openapi(spec)
+        return spec
+
+    def _mark_order_openapi(self, spec: dict[str, Any]):
+        """
+        Add x-fal-order-* keys to the OpenAPI specification to help the rendering of UI.
+
+        NOTE: We rely on the fact that fastapi and Python dicts keep the order of properties.
+        """
+
+        def mark_order(obj: dict[str, Any], key: str):
+            obj[f"x-fal-order-{key}"] = list(obj[key].keys())
+
+        mark_order(spec, "paths")
+
+        def order_schema_object(schema: dict[str, Any]):
+            """
+            Mark the order of properties in the schema object.
+            They can have 'allOf', 'properties' or '$ref' key.
+            """
+            if "allOf" in schema:
+                for sub_schema in schema["allOf"]:
+                    order_schema_object(sub_schema)
+            if "properties" in schema:
+                mark_order(schema, "properties")
+
+        for key in spec["components"].get("schemas") or {}:
+            order_schema_object(spec["components"]["schemas"][key])
+
+        return spec
+
+
+@mainify
+def endpoint(path: str) -> Callable[[EndpointT], EndpointT]:
+    """Designate the decorated function as an application endpoint."""
+
+    def marker_fn(callable: EndpointT) -> EndpointT:
+        if hasattr(callable, "route_signature"):
+            raise ValueError(
+                f"Can't set multiple routes for the same function: {callable.__name__}"
+            )
+
+        callable.route_signature = RouteSignature(path=path)  # type: ignore
+        return callable
+
+    return marker_fn

fal/cli.py

@@ -9,9 +9,7 @@ from uuid import uuid4
 
 import click
 import fal.auth as auth
-import grpc
-import openapi_fal_rest.api.billing.get_user_details as get_user_details
-import openapi_fal_rest.api.logs.list_since as list_logs
+import fal
 from fal import api, sdk
 from fal.console import console
 from fal.exceptions import ApplicationExceptionHandler
@@ -19,10 +17,13 @@ from fal.logging import get_logger, set_debug_logging
 from fal.logging.isolate import IsolateLogPrinter
 from fal.logging.trace import get_tracer
 from fal.rest_client import REST_CLIENT
-from fal.sdk import KeyScope
+from fal.sdk import AliasInfo, KeyScope
 from isolate.logs import Log, LogLevel, LogSource
 from rich.table import Table
 
+import openapi_fal_rest.api.billing.get_user_details as get_user_details
+import openapi_fal_rest.api.logs.list_since as list_logs
+
 DEFAULT_HOST = "api.alpha.fal.ai"
 HOST_ENVVAR = "FAL_HOST"
 
@@ -144,15 +145,6 @@ def auth_cli():
 @auth_cli.command(name="login")
 def auth_login():
     auth.login()
-    try:
-        client = sdk.FalServerlessClient(f"{DEFAULT_HOST}:{DEFAULT_PORT}")
-        with client.connect() as connection:
-            connection.list_aliases()
-    except grpc.RpcError as e:
-        if "Insufficient permissions" in e.details():
-            console.print(e.details())
-        else:
-            raise e
 
 
 @auth_cli.command(name="logout")
@@ -231,6 +223,10 @@ def key_revoke(client: sdk.FalServerlessClient, key_id: str):
 
 
 ##### Function group #####
+ALIAS_AUTH_OPTIONS = ["public", "private", "shared"]
+ALIAS_AUTH_TYPE = Literal["public", "private", "shared"]
+
+
 @click.group
 @click.option("--host", default=DEFAULT_HOST, envvar=HOST_ENVVAR)
 @click.option("--port", default=DEFAULT_PORT, envvar=PORT_ENVVAR, hidden=True)
@@ -239,12 +235,34 @@ def function_cli(ctx, host: str, port: str):
     ctx.obj = api.FalServerlessHost(f"{host}:{port}")
 
 
+def load_function_from(
+    host: api.FalServerlessHost,
+    file_path: str,
+    function_name: str,
+) -> api.IsolatedFunction:
+    import runpy
+
+    module = runpy.run_path(file_path)
+    if function_name not in module:
+        raise api.FalServerlessError(f"Function '{function_name}' not found in module")
+
+    target = module[function_name]
+    if isinstance(target, type) and issubclass(target, fal.App):
+        target = fal.wrap_app(target, host=host)
+
+    if not isinstance(target, api.IsolatedFunction):
+        raise api.FalServerlessError(
+            f"Function '{function_name}' is not a fal.function or a fal.App"
+        )
+    return target
+
+
 @function_cli.command("serve")
 @click.option("--alias", default=None)
 @click.option(
     "--auth",
     "auth_mode",
-    type=click.Choice(["public", "private", "shared"]),
+    type=click.Choice(ALIAS_AUTH_OPTIONS),
     default="private",
 )
 @click.argument("file_path", required=True)
@@ -255,17 +273,11 @@ def register_application(
     file_path: str,
     function_name: str,
     alias: str | None,
-    auth_mode: Literal["public", "private", "shared"],
+    auth_mode: ALIAS_AUTH_TYPE,
 ):
-    import runpy
-
     user_id = _get_user_id()
 
-    module = runpy.run_path(file_path)
-    if function_name not in module:
-        raise api.FalServerlessError(f"Function '{function_name}' not found in module")
-
-    isolated_function: api.IsolatedFunction = module[function_name]
+    isolated_function = load_function_from(host, file_path, function_name)
     gateway_options = isolated_function.options.gateway
     if "serve" not in gateway_options and "exposed_port" not in gateway_options:
         raise api.FalServerlessError(
@@ -279,14 +291,12 @@ def register_application(
             "Must expose port 8080 for now. This will be configurable in the future."
         )
 
-    max_concurrency = gateway_options.get("max_concurrency")
     id = host.register(
         func=isolated_function.func,
         options=isolated_function.options,
         application_name=alias,
         application_auth_mode=auth_mode,
-        max_concurrency=max_concurrency,
-        metadata={},
+        metadata=isolated_function.options.host.get("metadata", {}),
     )
 
     if id:
@@ -304,6 +314,15 @@ def register_application(
             console.print(f"URL: https://{user_id}-{id}.{gateway_host}")
 
 
+@function_cli.command("run")
+@click.argument("file_path", required=True)
+@click.argument("function_name", required=True)
+@click.pass_obj
+def run(host: api.FalServerlessHost, file_path: str, function_name: str):
+    isolated_function = load_function_from(host, file_path, function_name)
+    isolated_function()
+
+
 @function_cli.command("logs")
 @click.option("--lines", default=100)
 @click.option("--url", default=None)
@@ -341,57 +360,113 @@ def alias_cli(ctx, host: str, port: str):
     ctx.obj = api.FalServerlessClient(f"{host}:{port}")
 
 
-@alias_cli.command("list")
+def _alias_table(aliases: list[AliasInfo]):
+    table = Table(title="Function Aliases")
+    table.add_column("Alias")
+    table.add_column("Revision")
+    table.add_column("Auth")
+    table.add_column("Max Concurrency")
+    table.add_column("Max Multiplexing")
+    table.add_column("Keep Alive")
+
+    for app_alias in aliases:
+        table.add_row(
+            app_alias.alias,
+            app_alias.revision,
+            app_alias.auth_mode,
+            str(app_alias.max_concurrency),
+            str(app_alias.max_multiplexing),
+            str(app_alias.keep_alive),
+        )
+
+    return table
+
+
+@alias_cli.command("set")
+@click.argument("alias", required=True)
+@click.argument("revision", required=True)
+@click.option(
+    "--auth",
+    "auth_mode",
+    type=click.Choice(ALIAS_AUTH_OPTIONS),
+    default="private",
+)
 @click.pass_obj
-def alias_list(client: api.FalServerlessClient):
+def alias_set(
+    client: api.FalServerlessClient,
+    alias: str,
+    revision: str,
+    auth_mode: ALIAS_AUTH_TYPE,
+):
     with client.connect() as connection:
-        table = Table(title="Function Aliases")
-        table.add_column("Alias")
-        table.add_column("Revision")
-        table.add_column("Auth")
-        table.add_column("Max Concurrency")
+        connection.create_alias(alias, revision, auth_mode)
 
-        for app_alias in connection.list_aliases():
-            table.add_row(
-                app_alias.alias,
-                app_alias.revision,
-                app_alias.auth_mode,
-                str(app_alias.max_concurrency),
-            )
 
-    console.print(table)
+@alias_cli.command("delete")
+@click.argument("alias", required=True)
+@click.pass_obj
+def alias_delete(client: api.FalServerlessClient, alias: str):
+    with client.connect() as connection:
+        application_id = connection.delete_alias(alias)
 
+        console.print(f"Deleted alias '{alias}' for application '{application_id}'.")
 
-@alias_cli.command("scale")
-@click.argument("alias", required=True)
-@click.argument("max_concurrency", required=True, type=int)
+
+@alias_cli.command("list")
 @click.pass_obj
-def alias_scale(client: api.FalServerlessClient, alias: str, max_concurrency: int):
+def alias_list(client: api.FalServerlessClient):
     with client.connect() as connection:
-        connection.scale(application_name=alias, max_concurrency=max_concurrency)
+        aliases = connection.list_aliases()
+        table = _alias_table(aliases)
+
+    console.print(table)
 
 
 @alias_cli.command("update")
 @click.argument("alias", required=True)
-@click.option("--keep-alive", type=int)
-@click.option("--max-multiplexing", type=int)
+@click.option("--keep-alive", "-k", type=int)
+@click.option("--max-multiplexing", "-m", type=int)
+@click.option("--max-concurrency", "-c", type=int)
+# TODO: add auth_mode
+# @click.option(
+#     "--auth",
+#     "auth_mode",
+#     type=click.Choice(ALIAS_AUTH_OPTIONS),
+# )
 @click.pass_obj
 def alias_update(
     client: api.FalServerlessClient,
     alias: str,
     keep_alive: int | None,
     max_multiplexing: int | None,
+    max_concurrency: int | None,
 ):
     with client.connect() as connection:
-        if not (keep_alive or max_multiplexing):
+        if keep_alive is None and max_multiplexing is None and max_concurrency is None:
             console.log("No parameters for update were provided, ignoring.")
             return
 
-        connection.update_application(
+        alias_info = connection.update_application(
             application_name=alias,
             keep_alive=keep_alive,
             max_multiplexing=max_multiplexing,
+            max_concurrency=max_concurrency,
         )
+        table = _alias_table([alias_info])
+
+    console.print(table)
+
+
+@alias_cli.command("scale")
+@click.argument("alias", required=True)
+@click.argument("max_concurrency", required=True, type=int)
+def alias_scale(alias: str, max_concurrency: int):
+    alias_update.callback(
+        alias=alias,
+        keep_alive=None,
+        max_multiplexing=None,
+        max_concurrency=max_concurrency,
+    )  # type: ignore
 
 
 ##### Secrets group #####
@@ -461,30 +536,6 @@ def remove_http_and_port_from_url(url):
     return url
 
 
-# dbt-fal commands to be errored out
-DBT_FAL_COMMAND_NOTICE = """
-The dbt tool `fal` and `dbt-fal` adapter have been merged into a single tool.
-Please use the new `dbt-fal` command line tool instead.
-Running `pip install dbt-fal` will install the new tool and the adapter alongside.
-Then run your command like
-
-    dbt-fal <command>
-
-"""
-
-
-@cli.command("run", context_settings={"ignore_unknown_options": True})
-@click.argument("any", nargs=-1, type=click.UNPROCESSED)
-def dbt_run(any):
-    raise click.BadArgumentUsage(DBT_FAL_COMMAND_NOTICE)
-
-
-@cli.command("flow", context_settings={"ignore_unknown_options": True})
-@click.argument("any", nargs=-1, type=click.UNPROCESSED)
-def dbt_flow(any):
-    raise click.BadArgumentUsage(DBT_FAL_COMMAND_NOTICE)
-
-
 def _get_user_id() -> str:
     try:
         user_details_response = get_user_details.sync_detailed(

fal/exceptions/_base.py

@@ -14,4 +14,4 @@ class FalServerlessException(Exception):
         super().__init__(message)
 
     def __str__(self) -> str:
-        return self.message
+        return self.message + (f"\nHint: {self.hint}" if self.hint else "")

fal/exceptions/auth.py

@@ -9,5 +9,5 @@ class UnauthenticatedException(FalServerlessException):
     def __init__(self) -> None:
         super().__init__(
             message="You must be authenticated.",
-            hint="Login via `fal auth login`",
+            hint="Login via `fal auth login` or make sure to setup fal keys correctly.",
         )

fal/rest_client.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import fal.flags as flags
 from fal.sdk import get_default_credentials
+
 from openapi_fal_rest.client import Client