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)

Bases: _NativeUtensilSpec

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. Hosted properties such as utensil.image_generation can also be called with options to create a configured copy while preserving the bare zero-config form.

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.

ApplyPatchCall

ApplyPatchCall is the value passed to the function you give utensil.apply_patch(execute=...).

chatsnack.ApplyPatchCall(item_id: Optional[str], call_id: str, status: str, operation: Mapping[str, Any], caller: Optional[Mapping[str, Any]] = None, agent: Optional[Mapping[str, Any]] = None, created_by: Optional[str] = None, provider_extras: Mapping[str, Any] = (lambda: MappingProxyType({}))()) dataclass

Isolated Apply Patch request passed to the caller's executor.

call_id correlates the required provider output. item_id identifies the response item itself. The operation and provider extras are copied before execution so application code cannot mutate Chat history by accident.

from_normalized(tool_call: NormalizedToolCall) -> ApplyPatchCall classmethod

Build an isolated executor value from one normalized provider call.