Skip to content

Types

Shared types used throughout the harness. All are exported from the top-level data_harness package.

ToolSpec

data_harness.ToolSpec dataclass 

ToolSpec(
    name: str,
    description: str,
    input_schema: dict,
    handler: Callable[..., Any] | None = None,
    visible: bool = True,
    annotations: ToolAnnotations | None = None,
)

Everything the harness needs to register and dispatch one tool.

Attributes:

Name Type Description
name str

Unique tool name exposed to the model.
description str

Natural-language description shown to the model.
input_schema dict

JSON Schema object describing the tool's parameters.
handler Callable[..., Any] | None

Callable invoked with **tool_input when the model calls the tool. None means the tool is schema-only (not dispatchable).
visible bool

Whether the tool appears in the model's tool list. Hidden tools can still be called if the model somehow names them; set handler=None to block dispatch entirely.
annotations ToolAnnotations | None

Optional side-effect hints passed to ToolAnnotations.

to_provider_dict 

to_provider_dict() -> dict

Return the provider-facing tool dict (name, description, input_schema).

Source code in data_harness/types.py 
120
121
122
123
124
125
126
def to_provider_dict(self) -> dict:
    """Return the provider-facing tool dict (name, description, input_schema)."""
    return {
        "name": self.name,
        "description": self.description,
        "input_schema": self.input_schema,
    }

Message

data_harness.Message dataclass 

Message(
    role: Literal["user", "assistant"],
    content: list[ContentBlock],
)

A single turn in the conversation history.

Attributes:

Name Type Description
role Literal['user', 'assistant']

Either "user" or "assistant".
content list[ContentBlock]

Ordered list of content blocks for this turn.

TextBlock

data_harness.TextBlock dataclass 

TextBlock(text: str)

A plain-text content block inside a Message.

Attributes:

Name Type Description
text str

The raw text content.

ToolUseBlock

data_harness.ToolUseBlock dataclass 

ToolUseBlock(
    tool_use_id: str, tool_name: str, tool_input: dict
)

A tool-invocation block emitted by the model.

Attributes:

Name Type Description
tool_use_id str

Unique identifier for this invocation, echoed back in the matching ToolResultBlock.
tool_name str

Name of the tool to call.
tool_input dict

Parsed JSON arguments for the tool.

ToolResultBlock

data_harness.ToolResultBlock dataclass 

ToolResultBlock(
    tool_use_id: str, content: str, is_error: bool = False
)

The harness-side result of a tool invocation.

Attributes:

Name Type Description
tool_use_id str

Must match the tool_use_id of the originating ToolUseBlock.
content str

Serialised tool output, or an error message when is_error is True.
is_error bool

Whether the tool call raised an exception.

ToolAnnotations

data_harness.ToolAnnotations dataclass 

ToolAnnotations(
    title: str | None = None,
    read_only: bool | None = None,
    cache_mutating: bool | None = None,
    destructive: bool | None = None,
    open_world: bool | None = None,
)

Model-visible hints about a tool's side-effect profile.

All fields are optional. Omitted fields are treated as unknown by the harness; set them explicitly when the information is relevant to how the model should reason about the tool.

Attributes:

Name Type Description
title str | None

Human-readable display name for the tool.
read_only bool | None

True if the tool never mutates external state.
cache_mutating bool | None

True if the tool writes to the session cache.
destructive bool | None

True if the tool performs irreversible side effects.
open_world bool | None

True if the tool can reach external systems at runtime.

ContentBlock

ContentBlock is a type alias for the union of the three block types that can appear in a Message:

ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock