mechaharness.core.types

Shared domain types used across inference and harness layers.

These models form the stable public contract. Keep them serializable so future language bindings (via FFI / IPC / OpenAPI) can share the same shapes.

class mechaharness.core.types.ChatMessage(*, role: Role, content: str | None = None, name: str | None = None, tool_calls: list[ToolCall] | None = None, tool_call_id: str | None = None, reasoning_content: str | None = None, extra: dict[str, ~typing.Any]=<factory>)[source]

Bases: BaseModel

One turn in a chat transcript (portable across providers).

content: str | None

extra: dict[str, Any]

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None

reasoning_content: str | None

role: Role

tool_call_id: str | None

tool_calls: list[ToolCall] | None

class mechaharness.core.types.CompletionRequest(*, model: str, messages: list[~mechaharness.core.types.ChatMessage], tools: list[~mechaharness.core.types.ToolDefinition] | None = None, temperature: float | None = None, max_tokens: int | None = None, stop: list[str] | None = None, extra: dict[str, ~typing.Any] = <factory>)[source]

Bases: BaseModel

Normalized request handed to an InferenceStrategy.

extra: dict[str, Any]

max_tokens: int | None

messages: list[ChatMessage]

model: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

stop: list[str] | None

temperature: float | None

tools: list[ToolDefinition] | None

class mechaharness.core.types.CompletionResponse(*, message: ChatMessage, finish_reason: str | None = None, usage: Usage | None = None, raw: dict[str, Any] | None = None, cost: Any | None = None)[source]

Bases: BaseModel

Normalized response returned by an InferenceStrategy.

cost: Any | None

finish_reason: str | None

message: ChatMessage

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

raw: dict[str, Any] | None

usage: Usage | None

class mechaharness.core.types.Role(*values)[source]

Bases: str, Enum

ASSISTANT = 'assistant'

SYSTEM = 'system'

TOOL = 'tool'

USER = 'user'

class mechaharness.core.types.ToolCall(*, id: str, name: str, arguments: dict[str, ~typing.Any]=<factory>)[source]

Bases: BaseModel

Model-requested tool invocation (id, name, decoded arguments).

arguments: dict[str, Any]

id: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

class mechaharness.core.types.ToolDefinition(*, name: str, description: str = '', parameters: dict[str, ~typing.Any]=<factory>)[source]

Bases: BaseModel

Provider-agnostic tool/function schema exposed to a harness.

description: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

parameters: dict[str, Any]

class mechaharness.core.types.ToolResult(*, tool_call_id: str, content: str, is_error: bool = False)[source]

Bases: BaseModel

Result of executing a tool, fed back as a tool-role message.

content: str

is_error: bool

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tool_call_id: str

class mechaharness.core.types.Usage(*, prompt_tokens: int | None = None, completion_tokens: int | None = None, total_tokens: int | None = None)[source]

Bases: BaseModel

Token usage reported by a provider (fields may be unset).

completion_tokens: int | None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prompt_tokens: int | None

total_tokens: int | None