# Decorators

Public decorators for extending or integrating with the framework.

This module contains decorators that are part of the public API and intended
for end users to apply to their own functions or classes.

### contextgem.public.decorators.register_tool(func, /)

Registers a function as a tool for LLM chat with tools.

The function defines the tool: its name is the name of the tool, its docstring
describes the tool to the LLM, and its parameters, with their type hints and
default values, define the parameters of the tool. The descriptions of the
parameters are taken from the docstring, or from `Annotated` type hints, which
can also set constraints, e.g. `Annotated[int, Field(description="...", ge=1)]`.

Pass the decorated function to `tools` of the LLM.

* **Parameters:**
  **func** ([`collections.abc.Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] | [`collections.abc.Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`collections.abc.Coroutine`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Coroutine)[[`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]) – A function to be used as a tool. Can be sync or async, and must
  return a non-empty string.
* **Returns:**
  The same function, marked as a registered tool.
* **Return type:**
  [`collections.abc.Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] | [`collections.abc.Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`collections.abc.Coroutine`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Coroutine)[[`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]]
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the provided object is not callable, or if a parameter
    of the function has no type hint.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the signature cannot be inspected, if the function has
    positional-only parameters or accepts `*args` or `**kwargs`, if it has
    no docstring, or if the function name is empty.