calute.operators.types

Shared operator tool datatypes.

Defines the core value types used across the operator subsystem:

• ImageInspectionResult – structured result for local image inspection via the view_image tool.

• UserPromptOption and PendingUserPrompt – types that model user clarification questions.

• OperatorPlanStep and OperatorPlanState – types that represent the structured execution plan.

class calute.operators.types.ImageInspectionResult(path: str, format: str | None, mode: str, width: int, height: int, image: Image, detail: str = 'auto')

Bases: object

Structured result for local image inspection.

Returned by the view_image operator tool and carries both serialisable metadata (path, dimensions, format) and the in-memory PIL image for multimodal reinvocation.

path

Absolute filesystem path to the inspected image.

Type

str

format

Image format string reported by PIL (e.g. "PNG", "JPEG"). May be None if PIL could not determine the format.

Type

str | None

mode

PIL image mode string (e.g. "RGB", "RGBA").

Type

str

width

Image width in pixels.

Type

int

height

Image height in pixels.

Type

int

image

In-memory PIL Image instance.

Type

PIL.Image.Image

detail

Requested inspection detail level. Defaults to "auto".

Type

str

detail: str = 'auto'

format: str | None

height: int

image: Image

mode: str

path: str

summary() → str

Return a compact text summary safe for tool-message persistence.

Returns

A single-line string describing the image path, dimensions, mode, and format.

tool_metadata() → dict[str, Any]

Return serialisable metadata for session persistence.

Produces a dictionary that can be safely JSON-encoded and stored alongside tool call records, without including the heavy PIL image object.

Returns

A dictionary with keys path, format, mode, width, height, and detail.

width: int

class calute.operators.types.OperatorPlanState(explanation: str | None = None, steps: list[calute.operators.types.OperatorPlanStep] = <factory>, revision: int = 0, updated_at: str = <factory>)

Bases: object

Structured plan state updated by the operator plan tool.

Tracks a sequence of OperatorPlanStep items together with an explanation and a monotonically increasing revision counter.

explanation

Optional text explaining the current plan state or the most recent change.

Type

str | None

steps

Ordered list of OperatorPlanStep instances.

Type

list[calute.operators.types.OperatorPlanStep]

revision

Monotonically increasing counter bumped on every call to update().

Type

int

updated_at

ISO 8601 timestamp of the last update.

Type

str

explanation: str | None = None

revision: int = 0

steps: list[calute.operators.types.OperatorPlanStep]

to_dict() → dict[str, Any]

Serialise the plan state.

Returns

A dictionary with explanation, revision, updated_at, and steps (each serialised via OperatorPlanStep.to_dict()).

update(explanation: str | None, plan: list[dict[str, str]]) → dict[str, Any]

Replace the current plan state.

Atomically swaps the explanation and step list, increments the revision counter, and refreshes the timestamp.

Parameters

• explanation – Optional short note describing the plan change.

• plan – List of step dictionaries. Each must contain a "step" key; "status" defaults to "pending" when absent.

Returns

The serialised plan state produced by to_dict().

updated_at: str

class calute.operators.types.OperatorPlanStep(step: str, status: str = 'pending')

Bases: object

One step in the operator plan state.

step

Short description of what this step involves.

Type

str

status

Current status label (e.g. "pending", "in_progress", "completed"). Defaults to "pending".

Type

str

status: str = 'pending'

step: str

to_dict() → dict[str, str]

Serialise the plan step.

Returns

A dictionary with step and status keys.

class calute.operators.types.PendingUserPrompt(request_id: str, question: str, options: list[calute.operators.types.UserPromptOption] = <factory>, allow_freeform: bool = True, placeholder: str | None = None, created_at: str = <factory>)

Bases: object

Live question awaiting user input from the UI.

Created by UserPromptManager when the ask_user tool is invoked, and resolved once the user submits an answer through the TUI.

request_id

Unique identifier for this prompt request.

Type

str

question

The question text displayed to the user.

Type

str

options

Optional list of UserPromptOption instances the user can choose from.

Type

list[calute.operators.types.UserPromptOption]

allow_freeform

When True, the user may type a custom answer instead of selecting a listed option.

Type

bool

placeholder

Optional placeholder hint shown in the input field.

Type

str | None

created_at

ISO 8601 timestamp of when the prompt was created.

Type

str

allow_freeform: bool = True

created_at: str

options: list[calute.operators.types.UserPromptOption]

placeholder: str | None = None

question: str

request_id: str

to_dict() → dict[str, Any]

Serialise the pending prompt for UI polling.

Returns

A dictionary containing all prompt fields, with options serialised via UserPromptOption.to_dict().

class calute.operators.types.UserPromptOption(label: str, value: str | None = None)

Bases: object

Single selectable option for a pending user question.

label

Human-readable display text for the option.

Type

str

value

Machine-readable value submitted when this option is selected. Defaults to the label when None.

Type

str | None

label: str

to_dict() → dict[str, str]

Serialise the option for UI and persistence use.

Returns

A dictionary with label and value keys. When value was None, the label is used as the value.

value: str | None = None

calute.operators.types.now_iso() → str

Return the current UTC time as an ISO 8601 string.

Returns

A timezone-aware ISO 8601 timestamp string representing the current moment in UTC.

Example

>>> ts = now_iso()
>>> "T" in ts
True