yr.tool

tool(
    fn: Callable | None = None,
    creds: str | list[str] | None = None,
    insert_result: bool = True,
) → DecoratedTool | Callable[[Callable], DecoratedTool]

Decorate a Python function as a Yera tool.

Tools are self-contained chunks of Python an @app can call into — the app's LLM drives control flow, deciding when and with what arguments to invoke each tool. Usable bare (@tool) or with keyword arguments (@tool(creds=...)).

If creds is provided, the named credential groups are resolved from the active Yera profile and bound to the tool's context before the function body runs; the body reads them back via tool_creds.

Parameters

fn
type: Callable | None = None

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

creds
type: str | list[str] | None = None

Credential group(s) the tool needs access to. A single group name, a list of group names, or None for no credentials. Group names are configured in the active Yera profile; the resolved keys appear as <group>.<subkey> in tool_creds.

insert_result
type: bool = True

Whether to append the tool's return value to the active LLM context. When False, the Python caller still receives the value, but it is not included in later model requests.

Returns

type: DecoratedTool | Callable[[Callable], DecoratedTool]

A DecoratedTool callable that resolves credentials and runs the function under the tool credential context when invoked. When called with arguments (fn is None), returns a decorator that produces the wrapper.

Raises

InvalidToolCredsArgumentError

If creds is not None, a str, or list[str].

Examples

Use the bare decorator for a tool with default behavior:

python
import yera as yr

@yr.tool
def celsius_to_fahrenheit(temperature: float) -> float:
    return temperature * 9 / 5 + 32

Configure credentials and keep a sensitive result out of the model context:

python
import yera as yr

@yr.tool(creds="travel", insert_result=False)
def booking_headers() -> dict[str, str]:
    token = yr.tool_creds().require("travel.token")
    return {"Authorization": f"Bearer {token}"}