yr.tool

tool(
    fn: Callable | None = None,
    creds: str | list[str] | None = None,
) → 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.

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].

Example:

    @yr.tool(creds=["db"])
    def get_customer(customer_id: str) -> dict:
        creds = yr.tool_creds()
        conn = psycopg.connect(
            host=creds.require("db.host"),
            port=creds.require("db.port"),
            user=creds.require("db.user"),
            password=creds.require("db.password"),
        )
        with conn.cursor() as cur:
            cur.execute("SELECT * FROM customers WHERE id = %s", (customer_id,))
            return cur.fetchone()