yera.apps.decorator

App function wrapping and the @app decorator.

Provides AppFunctionWrapper, which adapts a plain Python function into a Yera app — validating its signature against the supported type system, registering it with the app registry, and driving the execution lifecycle (event stream, model contexts, system prompt, argument coercion, return-type checking, exit-event handling).

The app decorator is the normal entry point; wrappers are not to be constructed directly.

Symbols

def app — Decorator that turns a Python function into a Yera app.
class AppFunctionWrapper — Wraps a Python function as a Yera app.

app

app(
    fn: Callable | None = None,
    name: str | None = None,
    description: str | None = None,
    model: LLMContext | None = None,
    sys_prompt: str | None = None,
) → AppFunctionWrapper | Callable[[Callable], AppFunctionWrapper]

Decorator that turns a Python function into a Yera app.

Usable bare (@app) or with keyword arguments (@app(name=..., model=..., sys_prompt=...)). The wrapped function's signature is validated against Yera's supported type system at decoration time; arguments and return values are coerced at call time.

Parameters

fn
type: Callable | None = None

The function being decorated when used bare. Left as None when the decorator is invoked with arguments.

name
type: str | None = None

Display name for the app. Defaults to the function's __name__.

description
type: str | None = None

Optional human-readable description recorded in the app metadata.

model
type: LLMContext | None = None

Optional LLMContext entered for the duration of each run. Falls back to the active profile's default model if omitted.

sys_prompt
type: str | None = None

Optional system prompt emitted once the model context is entered.

Returns

type: AppFunctionWrapper | Callable[[Callable], AppFunctionWrapper]

An AppFunctionWrapper callable that runs the function under the Yera event-stream runtime when invoked. When called with arguments (fn is None), returns a decorator that produces the wrapper.

AppFunctionWrapper

Wraps a Python function as a Yera app.

Validates the wrapped function's signature against Yera's supported type system, registers it in the app registry under its module-qualified identifier, and drives the execution lifecycle: event-stream setup, model-context entry, system-prompt emission, argument coercion, return-type checking, and exit-event handling.

At the top of the call stack, execution runs in a subprocess with console output streamed via the rich renderer. When called from within an existing app context (nested), execution runs directly in the current process.

Instances are normally produced by the app decorator rather than constructed directly.

Parameters

app_function
type: Callable

The Python function to wrap.

name
type: str | None

Optional display name. Defaults to the function's name.

description
type: str | None

Optional human-readable description.

model
type: LLMContext | None

Optional LLMContext entered for the duration of each run.

sys_prompt_str
type: str | None

Optional system prompt emitted at run start.

Attributes

metadata

AppMetadata describing this app.

Methods

invoke — Execute the wrapped function with the full app lifecycle.
__call__ — Invoke the app.
__reduce__ — Support pickling via ``cloudpickle``.

AppFunctionWrapper.invoke

invoke(
    *args,
    **kwargs,
) → object

Execute the wrapped function with the full app lifecycle.

Coerces arguments to their declared types, enters the resolved model context (the supplied model or the ambient default), emits the configured system prompt, calls the underlying function, validates the return value against the declared return type, and routes both the success and failure paths through _handle_app_exit.

This is the core execution method. __call__ dispatches to it either via a subprocess (top-level runs) or directly (nested runs); callers should use __call__ rather than invoke directly.

Parameters

*args
type: object = ()

Positional arguments forwarded to the wrapped function after coercion to their declared types.

**kwargs
type: object

Keyword arguments forwarded to the wrapped function after coercion to their declared types.

Returns

type: object

The wrapped function's return value on success, or None if this is a top-level run that ended in a handled failure.

Raises

TypeError

If arguments cannot be bound to the signature or coerced to their declared types.

Exception

Re-raises the underlying exception when a nested run fails and no failure exit event has already been pushed.

AppFunctionWrapper.__call__

__call__(
    *args,
    **kwargs,
) → object

Invoke the app.

At the top of the app stack, runs the app under the console renderer so that events are pretty-printed as they stream, and returns the coerced return value once the run finishes. When nested inside an already-active app context, delegates to invoke.

Parameters

*args
type: object = ()

Positional arguments for the wrapped function.

**kwargs
type: object

Not supported, yet. Variadic keyword splats (**kwargs) in app definitions cannot be statically analysed by the (upcoming) SIGL compiler and are rejected at decoration time. Non-splat ones will be fine.

Returns

type: object

The wrapped function's return value, coerced to the declared return type.

Raises

NotImplementedError

If any keyword arguments are supplied.

AppRuntimeError

If the run does not terminate with an exit block, or exits with a non-zero exit code. See AppRuntimeError.

AppFunctionWrapper.__reduce__

__reduce__() → tuple[Callable, tuple]

Support pickling via cloudpickle.

The wrapped function is serialised with cloudpickle (rather than the standard pickle) so that closures, lambdas, and locally defined functions survive the round trip. On unpickling, _unpickle_app_wrapper reconstructs the AppFunctionWrapper by re-running the decorator over the restored function.