Defining your Functions

Muna supports compiling a tiny-but-growing subset of Python language constructs. Below are requirements and guidelines for compiling a Python function with Muna:

Specifying the Function Signature

The prediction function must be a module-level function, and must have parameter and return type annotations:

from muna import compile

@compile(...)
def greeting(name: str) -> str:
    return f"Hello {name}"

The prediction function must not have any variable-length positional or keyword arguments.

Supported Parameter Types

Muna supports a fixed set of predictor input and output value types. Below are supported type annotations:

Floating Point Values

Floating-point input and return values should be annotated with the float built-in type.

from muna import compile

@compile(...)
def square(number: float) -> float:
    return number ** 2

Unlike Python which defaults to 64-bit floats, Muna will always lower a Python float to 32 bits.

For control over the binary width of the number, use the numpy.float[16,32,64] types:

from muna import compile
import numpy as np

@compile(...)
def square(number: np.float64) -> float64:
    return number ** 2

Integer Values

Integer input and return values should be annotated with the int built-in type.

from muna import compile

@compile(...)
def square(number: int) -> int:
    return number ** 2

Unlike Python which supports arbitrary-precision integers, Muna will always lower a Python int to 32 bits.

For control over the binary width of the integer, use the numpy.int[8,16,32,64] types:

from muna import compile
import numpy as np

@compile(...)
def square(number: np.int16) -> np.int16:
    return number ** 2

Boolean Values

Boolean input and return values must be annotated with the bool built-in type.

from muna import compile

@compile(...)
def invert(on: bool) -> bool:
    return not on

Tensor Values

Tensor input and return values must be annotated with the NumPy numpy.typing.NDArray[T] type, where T is the tensor element type.

from muna import compile
import numpy as np
from numpy.typing import NDArray

@compile(...)
def cholesky_decompose(tensor: NDArray[np.float64]) -> np.ndarray:
    return np.linalg.cholesky(tensor).astype("float32")

You can also annotate with the np.ndarray type, but doing so will always assume a float32 element type (following PyTorch semantics).

Below are the supported element types:

Numpy data type	Muna data type
`np.float16`	`float16`
`np.float32`	`float32`
`np.float64`	`float64`
`np.int8`	`int8`
`np.int16`	`int16`
`np.int32`	`int32`
`np.int64`	`int64`
`np.uint8`	`uint8`
`np.uint16`	`uint16`
`np.uint32`	`uint32`
`np.uint64`	`uint64`
`bool`	`bool`

Muna does not yet support complex numbers or tensors.

Muna only supports, and will always assume, little-endian ordering for multi-byte element types.

String Values

String input and return values must be annotated with the str built-in type.

from muna import compile

@compile(...)
def uppercase(text: str) -> str:
    return text.upper()

List Values

List input and return values must be annotated with the list[T] built-in type, where T is the element type.

from muna import compile

@compile(...)
def slice(items: list[str]) -> list[str]:
    return items[:3]

When the list element type T is a Pydantic BaseModel, a full JSON schema will be generated.

Providing an element type T is optional but strongly recommended because it is used to generate a schema for the parameter or return value.

Dictionary Values

Dictionary input and return values can be annotated in one of two ways:

Using a Pydantic BaseModel subclass.
Using the dict[str, T] built-in type.

from muna import compile
from pydantic import BaseModel
from typing import Literal

class Person(BaseModel):
    city: str
    age: int

class Pet(BaseModel):
    sound: Literal["bark", "meow"]
    legs: int

@compile(...)
def choose_favorite_pet(person: Person) -> Pet:
    return Pet(sound="meow", legs=6)

We strongly recommend the Pydantic BaseModel annotation, as it allows us to generate a full JSON schema.

When using the dict annotation, they key type must be str. The value type T can be any arbitrary type.

Image Values

Image input and return values must be annotated with the Pillow PIL.Image.Image type.

from muna import compile
from PIL import Image

@compile(...)
def resize(image: Image.Image) -> Image.Image:
    return image.resize((512, 512))

Binary Values

Binary input and return values can be annotated in one of three ways:

Using the bytes built-in type.
Using the bytearray built-in type.
Using the io.BytesIO type.

from muna import compile
from PIL import Image

def resize_pixels(pixels: bytes) -> bytes
    return Image.frombytes("L", (4,4), pixels).resize((8,8)).tobytes()

Using Parameter Annotations

Muna supports attaching additional annotations to the function’s parameter and return types:

from muna import compile, Parameter
from typing import Annotated

@compile(...)
def area(
    radius: Annotated[
        float,
        Parameter.Generic(description="Radius of the circle.")
    ]
) -> Annotated[
    float,
    Parameter.Generic(description="Area of the circle.")
]:
    ...

These annotations serve multiple important purposes:

They help users know what input data to provide to the predictor and how to use output data from the predictor, via the parameter description.
They help users search for predictors using highly detailed queries (e.g. MCP clients).
They help the Muna client automatically provide familiar interfaces around your prediction function, e.g. with the OpenAI interface.
They help the Muna website automatically create interactive visualizers for your prediction function.

While not required, we highly recommend using parameter annotations on your compiled functions.

Below are currently supported annotations:

Generic Annotation

Use the Parameter.Generic annotation to provide information about a general input or output parameters:

predictor.py

from muna import compile, Parameter
from typing import Annotated

@compile(...)
def area(
    radius: Annotated[
        float,
        Parameter.Generic(description="Radius of the circle.")
    ]
) -> float:
    ...

Below is the full Parameter.Generic annotation definition:

@classmethod
def Generic(
    cls,
    *,
    description: str  # Parameter description.
) -> Parameter: ...

Numeric Annotation

Use the Parameter.Numeric annotation to specify numeric input or output parameters:

calculate_area.py

from muna import compile, Parameter
from typing import Annotated

@compile(...)
def area(
    radius: Annotated[
        float,
        Parameter.Numeric(
            description="Circle radius.",
            min=1.,
            max=12.
        )
    ]
) -> float:
    ...

Below is the full Parameter.Numeric annotation definition:

@classmethod
def Numeric(
    cls,
    *,
    description: str,         # Parameter description.
    min: float | None=None,   # Minimum value.
    max: float | None=None    # Maximum value.
) -> Parameter: ...

Audio Annotation

Use the Parameter.Audio annotation to specify audio parameters:

transcribe_audio.py

from muna import compile, Parameter
from numpy import ndarray
from typing import Annotated

@compile(...)
def transcribe_audio(
    audio: Annotated[
        ndarray,
        Parameter.Audio(
            description="Input audio.",
            sample_rate=24_000
        )
    ]
) -> str:
    ...

The Parameter.Audio annotation allows the compiled predictor to be used by the mock OpenAI speech client.

Below is the full Parameter.Audio annotation definition:

@classmethod
def Audio(
    cls,
    *,
    description: str, # Parameter description.
    sample_rate: int  # Audio sample rate in Hertz.
) -> Parameter: ...

Audio Speed Annotation

Use the Parameter.AudioSpeed annotation to specify audio speed parameters in audio generation predictors:

generate_speech.py

from muna import compile, Parameter
from numpy import ndarray
from typing import Annotated

@compile(...)
def generate_speech(
    text: str,
    speed: Annotated[
        float,
        Parameter.AudioSpeed(
            description="The speed of the generated audio.",
            min=0.25,
            max=4.0
        )
    ] = 1.0
) -> ndarray:
    ...

Below is the full Parameter.AudioSpeed annotation definition:

@classmethod
def AudioSpeed(
    cls,
    *,
    description: str,       # Parameter description.
    min: float | None=None, # Minimum audio speed.
    max: float | None=None  # Maximum audio speed.
) -> Parameter: ...

Audio Voice Annotation

Use the Parameter.AudioVoice annotation to specify audio voice parameters in audio generation predictors:

generate_speech.py

from muna import compile, Parameter
from numpy import ndarray
from typing import Annotated, Literal

Voice = Literal["almas", "parv", "rhea", "sam"]

@compile(...)
def generate_speech(
    text: str,
    voice: Annotated[
        Voice,
        Parameter.AudioVoice(description="Voice to use when generating audio.")
    ],
    speed: float=1.0
) -> ndarray:
    ...

Below is the full Parameter.AudioVoice annotation definition:

@classmethod
def AudioVoice(
    cls,
    *,
    description: str    # Parameter description.
) -> Parameter: ...

Bounding Box Annotation

Use the Parameter.BoundingBox or Parameter.BoundingBoxes annotations to specify bounding box parameters in object detection predictors:

from muna import compile, Parameter
from PIL import Image
from typing import Annotated, Literal

@compile(...)
def detect_object(
    image: Image.Image
) -> Annotated[
    Detection,
    Parameter.BoundingBox(description="Detected object.")
]:
    ...

Below is the full Parameter.BoundingBox annotation definition:

@classmethod
def BoundingBox(
    cls,
    *,
    description: str    # Parameter description.
) -> Parameter: ...

Depth Map Annotation

Use the Parameter.DepthMap annotation to specify depth map parameters in depth estimation predictors:

estimate_depth.py

from muna import compile, Parameter
from numpy import ndarray
from PIL import Image
from typing import Annotated

@compile(...)
def estimate_depth(
    image: Image.Image
) -> Annotated[
    ndarray,
    Parameter.DepthMap(description="Metric depth tensor.")
]:
    ...

Below is the full Parameter.DepthMap annotation definition:

@classmethod
def DepthMap(
    cls,
    *,
    description: str    # Parameter description.
) -> Parameter: ...

Embedding Annotation

Use the Parameter.Embedding annotation to specify vector embedding parameters in embedding predictors:

embed_text.py

from muna import compile, Parameter
from numpy import ndarray
from typing import Annotated

@compile(...)
def embed_text(
    text: str
) -> Annotated[
    ndarray,
    Parameter.Embedding(description="Embedding vector.")
]:
    ...

The Parameter.Embedding annotation allows the compiled predictor to be used by the mock OpenAI embedding client.

Below is the full Parameter.Embedding annotation definition:

@classmethod
def Embedding(
    cls,
    *,
    description: str  # Parameter description.
) -> Parameter: ...

Embedding Dimensions Annotation

Use the Parameter.EmbeddingDims annotation to specify an embedding Matryoshka dimension parameter in embedding predictors:

embed_text.py

from muna import compile, Parameter
from numpy import ndarray
from typing import Annotated

@compile(...)
def embed_text(
    text: str,
    dims: Annotated[
        int,
        Parameter.EmbeddingDims(description="Embedding dimensions.")
    ]
) -> ndarray:
    ...

Below is the full Parameter.EmbeddingDims annotation definition:

@classmethod
def EmbeddingDims(
    cls,
    *,
    description: str,       # Parameter description.
    min: int | None=None,   # Minimum embedding dimensions.
    max: int | None=None    # Maximum embedding dimensions.
) -> Parameter: ...

Writing the Function Body

The function body can contain arbitrary Python code. Given that the Muna compiler is currently a proof of concept, it has limited coverage for Python language features. Below is a list of Python language features that we either partially support, or do not support at all:

Functions

Statement	Status	Notes
Recursive functions	🔨	Recursive functions must have a return type annotation.
Lambda expressions	🚧	Lambda expressions can be invoked, but cannot be used as objects.

Literals

Collection	Status	Notes
List literals	🚧	List must contain primitive members (e.g. `int`, `str`).
Dictionary literals	🚧	Dictionary must contain primitive members (e.g. `int`, `str`).
Set literals	🚧	Set must contain primitive members (e.g. `int`, `str`).
Tuple literals	🚧	Tuple must contain primitive members (e.g. `int`, `str`).

Classes

Tracing through classes is not yet supported.

Exceptions

Statement	Status	Notes
`raise` statements	🔨
`try..except` statement	🔨

Over time the list of unsupported language features will shrink and eventually, will be empty.

Library Coverage

We are adding support for popular libraries, across tensor frameworks, scientific computing, and more:

Supported Libraries

Below are libraries currently supported by our compiler:

If you need a specific library to be supported by the Muna compiler, reach out to us.

Get Started

Making Predictions

Creating Predictors

Insiders

Defining your Functions

Specifying the Function Signature

Supported Parameter Types

Using Parameter Annotations

Writing the Function Body

Library Coverage

Get Started

Making Predictions

Creating Predictors

Insiders

​Specifying the Function Signature

​Supported Parameter Types

​Using Parameter Annotations

​Writing the Function Body

​Library Coverage

Specifying the Function Signature

Supported Parameter Types

Using Parameter Annotations

Writing the Function Body

Library Coverage