latent.agents.tool_decorator

@tool decorator for generating OpenAI function-calling schemas.

Functions

build_tool_meta

build_tool_meta(fn: Callable) -> dict[str, Any]

Build the _tool_meta dict ReActAgent reads to register a tool.

Shared between @tool and @retriever so any framework primitive that wants to be exposed to the LLM uses the same schema-builder.

tool

tool(fn: Callable) -> Callable

Mark a function as a tool for ReActAgent.

The function MUST have a docstring (used as the tool description) and type-annotated parameters (used to generate JSON Schema).

Two callable shapes are supported and the decorator unifies them: every decorated tool ends up as an async generator ReActAgent can drain. Coroutine tools (the common case — async def x(): return s) are auto-wrapped to yield their return value once; tools authored as async generators (the case where the body chains @retriever calls and wants to forward RetrieverStart / RetrieverEnd events) pass through unchanged. ReActAgent then async fors every tool uniformly — no isasyncgen branching at the call site.

Args: fn: The function to decorate. async def returning the tool result, OR an async def generator yielding events followed by a single non-event "result" yield. Sync functions raise ValueError — the agent pipeline is async end-to-end.

Returns: An async-generator wrapper carrying _tool_meta for ReActAgent introspection.

Raises: ValueError: If the function has no docstring.