Skip to content

Utensils

The public tool surface revolves around the module-level utensil helper plus the reusable grouped and hosted tool types behind it.

utensil

chatsnack.utensil.utensil = _UtensilNamespace() module-attribute

UtensilGroup

chatsnack.utensil.UtensilGroup(name: str, description: Optional[str] = None)

A group of related utensil functions that forms a searchable namespace.

Instances are both decorators (@group) and directly passable in utensils=[...].

Runtime behavior: Internally, a group compiles to a namespace tool dict via :meth:to_namespace_tool_dict. The namespace type is a Responses API concept that is only valid when tool_search is also present in the tools list.

At request time, chatsnack's transport normalization handles this automatically:

  • With tool_search present: the namespace wrapper is preserved so the provider can use tool_search to discover and defer-load the group's children.
  • Without tool_search: the namespace wrapper is dissolved and each child function is promoted to a top-level function tool. This makes groups work transparently on both the Responses API and the Chat Completions API.

Authors can always use UtensilGroup without worrying about the target runtime — the compile step picks the right shape.

add(func=None, *, name: Optional[str] = None, description: Optional[str] = None)

Decorator to add a function to this utensil group. Overwrites existing utensils with the same name.

get_openai_tools() -> List[Dict[str, str]]

Convert all utensils in this group to the OpenAI tools format.

to_namespace_tool_dict() -> Dict[str, Any]

Compile this group into a provider-shaped namespace tool dict.

The resulting dict uses type: "namespace" which is the internal authoring representation. The transport normalization layer (:meth:ResponsesNormalizationMixin._normalize_tools_for_responses_request) decides at request time whether to keep the wrapper (when tool_search is present) or flatten the children into individual function tools (when it is not).

HostedUtensil

chatsnack.utensil.HostedUtensil(tool_type: str, config: Optional[Dict[str, Any]] = None, include_entries: Optional[List[str]] = None)

A hosted OpenAI tool spec passable in utensils=[...].

Instances carry the provider tool definition and any implied params.responses.include entries so that Chat can wire both from a single utensils list without manual dict mutation.

to_tool_dict() -> Dict[str, Any]

Return the provider-shaped tool dict for the runtime.

get_include_entries() -> List[str]

Return any params.responses.include entries this tool implies.