fxn 0.0.40__py3-none-any.whl → 0.0.42__py3-none-any.whl

fxn/cli/{predict.py → predictions.py}

@@ -1,11 +1,11 @@
 # 
 #   Function
-#   Copyright © 2024 NatML Inc. All Rights Reserved.
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
 #
 
 from asyncio import run as run_async
 from io import BytesIO
-from numpy import ndarray
+from numpy import array_repr, ndarray
 from pathlib import Path, PurePath
 from PIL import Image
 from rich import print_json
@@ -14,34 +14,30 @@ from tempfile import mkstemp
 from typer import Argument, Context, Option
 
 from ..function import Function
+from ..types import Prediction
 from .auth import get_access_key
 
-def predict (
-    tag: str = Argument(..., help="Predictor tag."),
+def create_prediction (
+    tag: str=Argument(..., help="Predictor tag."),
+    quiet: bool=Option(False, "--quiet", help="Suppress verbose logging when creating the prediction."),
     context: Context = 0
 ):
-    run_async(_predict_async(tag, context=context))
+    run_async(_predict_async(tag, quiet=quiet, context=context))
 
-async def _predict_async (tag: str, context: Context):
+async def _predict_async (tag: str, quiet: bool, context: Context):
+    # Preload
+    fxn = Function(get_access_key())
+    fxn.predictions.create(tag, inputs={ }, verbose=not quiet)
+    # Predict
     with Progress(
         SpinnerColumn(spinner_name="dots"),
         TextColumn("[progress.description]{task.description}"),
         transient=True
     ) as progress:
         progress.add_task(description="Running Function...", total=None)
-        # Parse inputs
         inputs = { context.args[i].replace("-", ""): _parse_value(context.args[i+1]) for i in range(0, len(context.args), 2) }
-        # Stream
-        fxn = Function(get_access_key())
-        async for prediction in fxn.predictions.stream(tag, inputs=inputs):
-            # Parse results
-            images = [value for value in prediction.results or [] if isinstance(value, Image.Image)]
-            prediction.results = [_serialize_value(value) for value in prediction.results] if prediction.results is not None else None
-            # Print
-            print_json(data=prediction.model_dump())
-            # Show images
-            for image in images:
-                image.show()
+        prediction = fxn.predictions.create(tag, inputs=inputs)
+        _log_prediction(prediction)
 
 def _parse_value (value: str):
     """
@@ -70,33 +66,34 @@ def _parse_value (value: str):
         pass
     # File
     if value.startswith("@"):
-        return Path(value[1:])
+        path = Path(value[1:]).expanduser().resolve()
+        if path.suffix in [".txt", ".md"]:
+            with open(path) as f:
+                return f.read()
+        elif path.suffix in [".jpg", ".png"]:
+            return Image.open(path)
+        else:
+            with open(path, "rb") as f:
+                return BytesIO(f.read())
     # String
     return value
-    
+
+def _log_prediction (prediction: Prediction):
+    images = [value for value in prediction.results or [] if isinstance(value, Image.Image)]
+    prediction.results = [_serialize_value(value) for value in prediction.results] if prediction.results is not None else None
+    print_json(data=prediction.model_dump())
+    for image in images:
+        image.show()
+
 def _serialize_value (value):
-    # Convert ndarray to list
     if isinstance(value, ndarray):
-        return value.tolist()
-    # Write image
+        return array_repr(value)
     if isinstance(value, Image.Image):
         _, path = mkstemp(suffix=".png" if value.mode == "RGBA" else ".jpg")
         value.save(path)
         return path
-    # Serialize `BytesIO`
     if isinstance(value, BytesIO):
         return str(value)
-    # Serialize `Path`
     if isinstance(value, PurePath):
         return str(value)
-    # Return    
-    return value
-
-def _prediction_dict_factory (kv_pairs):
-    # Check if value
-    VALUE_KEYS = ["data", "type", "shape"]
-    keys = [k for k, _ in kv_pairs]
-    is_value = all(k in keys for k in VALUE_KEYS)
-    kv_pairs = [(k, v) for k, v in kv_pairs if v is not None] if is_value else kv_pairs
-    # Construct
-    return dict(kv_pairs)
+    return value

fxn/cli/predictors.py

@@ -1,14 +1,12 @@
 # 
 #   Function
-#   Copyright © 2024 NatML Inc. All Rights Reserved.
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
 #
 
 from rich import print_json
-from rich.progress import Progress, SpinnerColumn, TextColumn
-from typer import Argument, Option
+from typer import Argument
 
 from ..function import Function
-from ..types import PredictorStatus
 from .auth import get_access_key
 
 def retrieve_predictor (
@@ -17,50 +15,4 @@ def retrieve_predictor (
     fxn = Function(get_access_key())
     predictor = fxn.predictors.retrieve(tag)
     predictor = predictor.model_dump() if predictor else None
-    print_json(data=predictor)
-
-def list_predictors (
-    owner: str=Option(None, help="Predictor owner. This defaults to the current user."),
-    status: PredictorStatus=Option(PredictorStatus.Active, help="Predictor status. This defaults to `ACTIVE`."),
-    offset: int=Option(None, help="Pagination offset."),
-    count: int=Option(None, help="Pagination count.")
-):
-    fxn = Function(get_access_key())
-    predictors = fxn.predictors.list(
-        owner=owner,
-        status=status,
-        offset=offset,
-        count=count
-    )
-    predictors = [predictor.model_dump() for predictor in predictors] if predictors is not None else None
-    print_json(data=predictors)
-
-def search_predictors (
-    query: str=Argument(..., help="Search query."),
-    offset: int=Option(None, help="Pagination offset."),
-    count: int=Option(None, help="Pagination count.")
-):
-    fxn = Function(get_access_key())
-    predictors = fxn.predictors.search(query=query, offset=offset, count=count)
-    predictors = [predictor.model_dump() for predictor in predictors]
-    print_json(data=predictors)
-
-def delete_predictor (
-    tag: str=Argument(..., help="Predictor tag.")
-):
-    with Progress(
-        SpinnerColumn(spinner_name="dots"),
-        TextColumn("[progress.description]{task.description}"),
-        transient=True
-    ) as progress:
-        progress.add_task(description="Deleting Function...", total=None)
-        fxn = Function(get_access_key())
-        result = fxn.predictors.delete(tag)
-        print_json(data=result)
-
-def archive_predictor (
-    tag: str=Argument(..., help="Predictor tag.")
-):
-    fxn = Function(get_access_key())
-    predictor = fxn.predictors.archive(tag)
-    print_json(data=predictor.model_dump())
+    print_json(data=predictor)

fxn/client.py

@@ -0,0 +1,58 @@
+#
+#   Function
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
+#
+
+from json import loads, JSONDecodeError
+from pydantic import BaseModel
+from requests import request
+from typing import Any, Literal, Type, TypeVar
+
+T = TypeVar("T", bound=BaseModel)
+
+class FunctionClient:
+    
+    def __init__(self, access_key: str, api_url: str | None) -> None:
+        self.access_key = access_key
+        self.api_url = api_url or "https://api.fxn.ai/v1"
+
+    def request (
+        self,
+        *,
+        method: Literal["GET", "POST", "DELETE"],
+        path: str,
+        body: dict[str, Any]=None,
+        response_type: Type[T]=None
+    ) -> T:
+        response = request(
+            method=method,
+            url=f"{self.api_url}{path}",
+            json=body,
+            headers={ "Authorization": f"Bearer {self.access_key}" }
+        )
+        data = response.text
+        try:
+            data = response.json()
+        except JSONDecodeError:
+            pass
+        if response.ok:
+            return response_type(**data) if response_type is not None else None
+        else:
+            error = _ErrorResponse(**data).errors[0].message if isinstance(data, dict) else data
+            raise FunctionAPIError(error, response.status_code)
+
+class FunctionAPIError (Exception):
+
+    def __init__(self, message: str, status_code: int):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __str__(self):
+        return f"FunctionAPIError: {self.message} (Status Code: {self.status_code})"
+    
+class _APIError (BaseModel):
+    message: str
+
+class _ErrorResponse (BaseModel):
+    errors: list[_APIError]

fxn/compile/__init__.py

@@ -0,0 +1,7 @@
+# 
+#   Function
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
+#
+
+from .compile import compile
+from .sandbox import Sandbox

fxn/compile/compile.py

@@ -0,0 +1,80 @@
+# 
+#   Function
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
+#
+
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from pydantic import BaseModel, Field
+
+from ..types import AccessMode, Signature
+from .sandbox import Sandbox
+from .signature import get_function_type, infer_function_signature, FunctionType
+
+class PredictorSpec (BaseModel):
+    """
+    Descriptor of a predictor to be compiled.
+    """
+    tag: str = Field(description="Predictor tag.")
+    description: str = Field(description="Predictor description. MUST be less than 100 characters long.", min_length=4, max_length=100)
+    sandbox: Sandbox = Field(description="Sandbox to compile the function.")
+    access: AccessMode = Field(description="Predictor access.")
+    signature: Signature = Field(description="Predictor signature.")
+    card: str | None = Field(default=None, description="Predictor card (markdown).")
+    media: str | None = Field(default=None, description="Predictor media URL.")
+    license: str | None = Field(default=None, description="Predictor license URL. This is required for public predictors.")
+
+def compile (
+    tag: str,
+    *,
+    description: str,
+    sandbox: Sandbox=None,
+    access: AccessMode=AccessMode.Private,
+    card: str | Path=None,
+    media: Path=None,
+    license: str=None,
+):
+    """
+    Create a predictor by compiling a stateless function.
+
+    Parameters:
+        tag (str): Predictor tag.
+        description (str): Predictor description. MUST be less than 100 characters long.
+        sandbox (Sandbox): Sandbox to compile the function.
+        access (AccessMode): Predictor access.
+        card (str | Path): Predictor card markdown string or path to card.
+        media (Path): Predictor thumbnail image (jpeg or png) path.
+        license (str): Predictor license URL. This is required for public predictors.
+    """
+    def decorator (func: Callable):
+        # Check type
+        if not callable(func):
+            raise TypeError("Cannot compile non-function objects")
+        func_type = get_function_type(func)
+        if func_type not in { FunctionType.Function, FunctionType.Generator }:
+            raise TypeError(f"Function '{func.__name__}' must be a regular function or generator")
+        # Gather metadata
+        signature = infer_function_signature(func) # throws
+        if isinstance(card, Path):
+            with open(card_content, "r") as f:
+                card_content = f.read()
+        else:
+            card_content = card
+        spec = PredictorSpec(
+            tag=tag,
+            description=description,
+            sandbox=sandbox if sandbox is not None else Sandbox(),
+            access=access,
+            signature=signature,
+            card=card_content,
+            media=None, # INCOMPLETE
+            license=license
+        )
+        # Wrap
+        @wraps(func)
+        def wrapper (*args, **kwargs):
+            return func(*args, **kwargs)
+        wrapper.__predictor_spec = spec
+        return wrapper
+    return decorator

fxn/compile/sandbox.py

@@ -0,0 +1,177 @@
+# 
+#   Function
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
+#
+
+from __future__ import annotations
+from hashlib import sha256
+from pathlib import Path
+from pydantic import BaseModel
+from requests import put
+from typing import Literal
+
+from ..function import Function
+
+class WorkdirCommand (BaseModel):
+    kind: Literal["workdir"] = "workdir"
+    path: str
+
+class EnvCommand (BaseModel):
+    kind: Literal["env"] = "env"
+    env: dict[str, str]
+
+class UploadFileCommand (BaseModel):
+    kind: Literal["upload_file"] = "upload_file"
+    from_path: str
+    to_path: str
+    manifest: dict[str, str] | None = None
+
+class UploadDirectoryCommand (BaseModel):
+    kind: Literal["upload_dir"] = "upload_dir"
+    from_path: str
+    to_path: str
+    manifest: dict[str, str] | None = None
+
+class PipInstallCommand (BaseModel):
+    kind: Literal["pip_install"] = "pip_install"
+    packages: list[str]
+
+class AptInstallCommand (BaseModel):
+    kind: Literal["apt_install"] = "apt_install"
+    packages: list[str]
+
+class EntrypointCommand (BaseModel):
+    kind: Literal["entrypoint"] = "entrypoint"
+    path: str
+
+Command = (
+    WorkdirCommand          |
+    EnvCommand              |
+    UploadFileCommand       |
+    UploadDirectoryCommand  |
+    PipInstallCommand       |
+    AptInstallCommand       |
+    EntrypointCommand
+)
+
+class Sandbox (BaseModel):
+    """
+    Sandbox which defines a containerized environment for compiling your Python function.
+    """
+    commands: list[Command] = []
+
+    def workdir (self, path: str | Path) -> Sandbox:
+        """
+        Change the current working directory for subsequent commands.
+
+        Parameters:
+            path (str | Path): Path to change to.
+        """
+        command = WorkdirCommand(path=str(path))
+        self.commands.append(command)
+        return self
+
+    def env (self, **env: str) -> Sandbox:
+        """
+        Set environment variables in the sandbox.
+        """
+        command = EnvCommand(env=env)
+        self.commands.append(command)
+        return self
+
+    def upload_file (
+        self,
+        from_path: str | Path,
+        to_path: str | Path = "./"
+    ) -> Sandbox:
+        """
+        Upload a file to the sandbox.
+
+        Parameters:
+            from_path (str | Path): File path on the local file system.
+            to_path (str | Path): Remote path to upload file to.
+        """
+        command = UploadFileCommand(from_path=str(from_path), to_path=str(to_path))
+        self.commands.append(command)
+        return self
+
+    def upload_directory (
+        self,
+        from_path: str | Path,
+        to_path: str | Path = "."
+    ) -> Sandbox:
+        """
+        Upload a directory to the sandbox.
+
+        Parameters:
+            from_path (str | Path): Directory path on the local file system.
+            to_path (str | Path): Remote path to upload directory to.
+        """
+        command = UploadDirectoryCommand(from_path=str(from_path), to_path=str(to_path))
+        self.commands.append(command)
+        return self
+
+    def pip_install (self, *packages: str) -> Sandbox:
+        """
+        Install Python packages in the sandbox.
+
+        Parameters:
+            packages (list): Packages to install.
+        """
+        command = PipInstallCommand(packages=packages)
+        self.commands.append(command)
+        return self
+
+    def apt_install (self, *packages: str) -> Sandbox:
+        """
+        Install Debian packages in the sandbox.
+
+        Parameters:
+            packages (list): Packages to install.
+        """
+        command = AptInstallCommand(packages=packages)
+        self.commands.append(command)
+        return self
+    
+    def populate (self, fxn: Function=None) -> Sandbox:
+        """
+        Populate all metadata.
+        """
+        fxn = fxn if fxn is not None else Function()
+        for command in self.commands:
+            if isinstance(command, UploadFileCommand):
+                from_path = Path(command.from_path)
+                to_path = Path(command.to_path)
+                command.manifest = { str(to_path / from_path.name): self.__upload_file(from_path, fxn=fxn) }
+            elif isinstance(command, UploadDirectoryCommand):
+                from_path = Path(command.from_path)
+                to_path = Path(command.to_path)
+                files = [file for file in from_path.rglob("*") if file.is_file()]
+                command.manifest = { str(to_path / file.relative_to(from_path)): self.__upload_file(file, fxn=fxn) for file in files }
+        return self
+
+    def __upload_file (self, path: Path, fxn: Function) -> str:
+        assert path.is_file(), "Cannot upload file at path {path} because it is not a file"
+        hash = self.__compute_hash(path)
+        try:
+            fxn.client.request(method="HEAD", path=f"/resources/{hash}")
+        except:
+            resource = fxn.client.request(
+                method="POST",
+                path="/resources",
+                body={ "name": hash },
+                response_type=_Resource
+            )
+            with path.open("rb") as f:
+                put(resource.url, data=f).raise_for_status()
+        return hash
+    
+    def __compute_hash (self, path: Path) -> str:
+        hash = sha256()
+        with path.open("rb") as f:
+            for chunk in iter(lambda: f.read(4096), b""):
+                hash.update(chunk)
+        return hash.hexdigest()
+    
+class _Resource (BaseModel):
+    url: str

fxn/compile/signature.py

@@ -0,0 +1,183 @@
+# 
+#   Function
+#   Copyright © 2025 NatML Inc. All Rights Reserved.
+#
+
+from collections.abc import Mapping, Sequence
+from enum import Enum
+from inspect import isasyncgenfunction, iscoroutinefunction, isgeneratorfunction, signature
+from io import BytesIO
+import numpy as np
+from PIL import Image
+from pydantic import BaseModel, TypeAdapter
+from typing import get_type_hints, get_origin, get_args, Any, Dict, List, Union
+
+from ..types import Dtype, EnumerationMember, Parameter, Signature
+
+class FunctionType (str, Enum):
+    Coroutine = "ASYNC_FUNCTION"
+    Function = "FUNCTION"
+    Generator = "GENERATOR"
+    AsyncGenerator = "ASYNC_GENERATOR"
+
+def get_function_type (func) -> FunctionType:
+    if isasyncgenfunction(func):
+        return FunctionType.AsyncGenerator
+    elif iscoroutinefunction(func):
+        return FunctionType.Coroutine
+    elif isgeneratorfunction(func):
+        return FunctionType.Generator
+    else:
+        return FunctionType.Function
+
+def infer_function_signature (func) -> Signature:
+    inputs = _get_input_parameters(func)
+    outputs = _get_output_parameters(func)
+    signature = Signature(inputs=inputs, outputs=outputs)
+    return signature
+
+def _get_input_parameters (func) -> list[Parameter]:
+    sig = signature(func)
+    type_hints = get_type_hints(func)
+    parameters = []
+    for name, param in sig.parameters.items():
+        param_type = type_hints.get(name)
+        if param_type is None:
+            raise TypeError(f"Missing type annotation for parameter '{name}' in function '{func.__name__}'")
+        dtype = _infer_dtype(param_type)
+        enumeration = [EnumerationMember(
+            name=member.name,
+            value=member.value
+        ) for member in param_type] if _is_enum_subclass(param_type) else None
+        value_schema = _get_type_schema(param_type) if dtype in { Dtype.list, Dtype.dict } else None
+        input_param = Parameter(
+            name=name,
+            type=dtype,
+            description=None,
+            optional=param.default != param.empty,
+            range=None,
+            enumeration=enumeration,
+            value_schema=value_schema
+        )
+        parameters.append(input_param)
+    return parameters
+
+def _get_output_parameters (func) -> list[Parameter]:
+    # Check for return annotation
+    sig = signature(func)
+    if sig.return_annotation is sig.empty:
+        raise TypeError(f"Missing return type annotation for function '{func.__name__}'")
+    # Gather return types
+    return_types = []
+    if _is_tuple_type(sig.return_annotation):
+        return_types = get_args(sig.return_annotation)
+        if not return_types or Ellipsis in return_types:
+            raise TypeError(f"Return type of function '{func.__name__}' must be fully typed with generic type arguments.")
+    else:
+        return_types = [sig.return_annotation]
+    # Create parameters
+    parameters = [_get_output_parameter(f"output{idx}", output_type) for idx, output_type in enumerate(return_types)]
+    return parameters
+    
+def _get_output_parameter (name: str, return_type) -> Parameter:
+    dtype = _infer_dtype(return_type)
+    enumeration = [EnumerationMember(
+        name=member.name,
+        value=member.value
+    ) for member in return_type] if _is_enum_subclass(return_type) else None
+    value_schema = _get_type_schema(return_type) if dtype in { Dtype.list, Dtype.dict } else None
+    parameter = Parameter(
+        name=name,
+        type=dtype,
+        description=None,
+        optional=False,
+        range=None,
+        enumeration=enumeration,
+        value_schema=value_schema
+    )
+    return parameter
+
+def _infer_dtype (param_type) -> Dtype:
+    param_type = _strip_optional(param_type)
+    origin = get_origin(param_type)
+    args = get_args(param_type)
+    if origin is None:
+        if param_type is np.ndarray:
+            return Dtype.float32
+        elif param_type is Image.Image:
+            return Dtype.image
+        elif param_type in { bytes, bytearray, memoryview, BytesIO }:
+            return Dtype.binary
+        elif param_type is int:
+            return Dtype.int32
+        elif param_type is float:
+            return Dtype.float32
+        elif param_type is bool:
+            return Dtype.bool
+        elif param_type is str:
+            return Dtype.string
+        elif _is_enum_subclass(param_type):
+            return Dtype.string
+        elif param_type is list:
+            return Dtype.list
+        elif param_type is dict:
+            return Dtype.dict
+        elif _is_pydantic_model(param_type):
+            return Dtype.dict
+        else:
+            raise TypeError(f"Unsupported parameter type: {param_type}")
+    else:
+        if origin in { list, List, Sequence }:
+            return Dtype.list
+        elif origin in { dict, Dict, Mapping }:
+            return Dtype.dict
+        elif origin is np.ndarray:
+            if args:
+                dtype_arg = args[0]
+                dtype = _numpy_to_fxn_dtype(dtype_arg)
+                if dtype is not None:
+                    return dtype
+            return Dtype.float32
+        else:
+            raise TypeError(f"Unsupported parameter type: {param_type}")
+
+def _is_enum_subclass (cls) -> bool:
+    return isinstance(cls, type) and issubclass(cls, Enum)
+
+def _is_pydantic_model (cls) -> bool:
+    return isinstance(cls, type) and issubclass(cls, BaseModel)
+
+def _is_tuple_type (param_type) -> bool:
+    origin = get_origin(param_type)
+    return origin is tuple
+
+def _strip_optional (param_type):
+    if get_origin(param_type) is Union:
+        args = get_args(param_type)
+        non_none_args = [arg for arg in args if arg is not type(None)]
+        if len(non_none_args) == 1:
+            return non_none_args[0]
+    return param_type
+
+def _numpy_to_fxn_dtype (dtype) -> Dtype | None:
+    dtype_mapping = {
+        np.int8:    Dtype.int8,
+        np.int16:   Dtype.int16,
+        np.int32:   Dtype.int32,
+        np.int64:   Dtype.int64,
+        np.uint8:   Dtype.uint8,
+        np.uint16:  Dtype.uint16,
+        np.uint32:  Dtype.uint32,
+        np.uint64:  Dtype.uint64,
+        np.float16: Dtype.float16,
+        np.float32: Dtype.float32,
+        np.float64: Dtype.float64,
+        np.bool_:   Dtype.bool,
+    }
+    return dtype_mapping.get(dtype, None)
+
+def _get_type_schema (param_type) -> dict[str, Any] | None:
+    try:
+        return TypeAdapter(param_type).json_schema(mode="serialization")
+    except Exception:
+        return None