Tools

Tools are Python callables exposed to STATEK jobs. Decorators attach metadata used by prompt formatting, provider tool payloads, and execution.

Symbol	Import path	Purpose	Stability
`tool`	`statek.system` or `statek`	Mark a callable as an agent tool	Core
`subtask`	`statek.system` or `statek`	Mark a callable as a subtask factory	Core
`error_handler`	`statek.system` or `statek`	Mark a job termination handler	Core
`docstr`, `brief`	`statek.system` or `statek`	Print LLM-facing documentation	Core system tools
`panic`	`statek.system`	Raise current task difficulty	Core system tool
`python_cli`	`statek.system`	Execute code in `DIRECT` chat style	Core system tool
`find_sub_task_handler`	`statek.system` or `statek`	Find completed subtask notifications	Core system tool
`docs_style`	`statek.system` or `statek`	Configure docstring formatting	Advanced
`get_any`, `get_all`	`statek.system` or `statek`	Tool wrappers for future combination	Advanced

`@tool`

def tool(
    f=None,
    *,
    system: bool = False,
    target=None,
    error_handler=None,
    hidden: bool = False,
)

Marks a sync or async callable as a STATEK tool.

Parameters

Name	Description
`f`	Callable when used as `@tool`; omitted when used as `@tool(...)`.
`system`	Classifies the tool as system-level rather than application-level.
`target`	Optional `ChatStyle` or collection of styles for filtering.
`error_handler`	Optional valid `@error_handler` callable registered with the tool result.
`hidden`	Excludes the tool from LLM-facing discovery and provider tool payloads.

Returns: a wrapped callable with STATEK tool metadata.

Raises: TypeError when the error handler protocol is invalid or the callable signature cannot accept STATEK context injection.

from statek import tool
 
@tool
def lookup_order(order_id: str, **kwargs) -> str:
    """Return a short order summary."""
    return f"order={order_id}"

`@subtask`

def subtask(f=None, *, system: bool = False, target=None)

Marks a callable as a subtask factory. The decorated callable must accept **kwargs and return Job or SubTaskHandler. The wrapper exposes a framework-managed optional id.

Returns: a tool wrapper whose return annotation is SubTaskHandler.

Raises: TypeError for invalid signatures or unsupported return values.

from statek import subtask
from statek.task import create_new_job
 
@subtask
def research_topic(topic: str, **kwargs):
    return create_new_job(researcher, topic=topic)

`@error_handler`

def error_handler(func: Callable) -> Callable

Marks a callable as a job error handler. A valid handler name starts with _ and accepts (context, error=None).

For cleanup usage, deferred future registration, and critical-error behavior, see Error Handling.

from statek import error_handler, tool
 
@error_handler
def _notify_user(user_id: str, error=None):
    print(f"job failed for {user_id}: {error}")
 
@tool(error_handler=_notify_user)
def reserve_for_user(user_id: str, **kwargs) -> str:
    return user_id

System documentation tools

Function	Signature	Description
`docstr`	`docstr(what, method_name=None, **kwargs)`	Prints detailed documentation for a tool, class, object, or method.
`brief`	`brief(what, method_name=None, **kwargs)`	Prints short documentation for a tool, class, object, or method.
`docs_style`	`docs_style(f=None, *, brief_types=False)`	Advanced decorator for adjusting generated docs.

These tools print to the current job console and return None.

See Agent-Exposed Docstring Conventions for supported docstring sections, VARIANTS/:.../TOOL:..., brief signatures, and STATEK-ACL.

Runtime system tools

Function	Signature	Returns	Errors
`panic`	`panic(**kwargs)`	`None`	Raises `RuntimeError` outside a job context.
`python_cli`	`python_cli(code: str, **kwargs)`	`None`	Executes through the job step machinery in `DIRECT` style.
`find_sub_task_handler`	`find_sub_task_handler(id=None, **kwargs)`	`SubTaskHandler	None`
`get_any`	`get_any(args, *kwargs)`	`CombinedFutureResult`	Raises from future evaluation when no value is ready.
`get_all`	`get_all(args, *kwargs)`	`CombinedFutureResult`	Raises from future evaluation when not all values are ready.

Related APIs: Subtasks, Futures, Chat Styles.

Jobs Subtasks