| """The closed action vocabulary. |
| |
| A tiny model is only dependable when its output space is small and every mistake |
| is cheap to catch. The harness therefore accepts exactly six verbs, and validates |
| each field *before* anything touches the machine. |
| """ |
|
|
| from __future__ import annotations |
|
|
| from dataclasses import dataclass |
| from typing import Any, Final, Mapping |
|
|
| ACTION_KINDS: Final[tuple[str, ...]] = ("click", "type", "key", "scroll", "wait", "done") |
|
|
|
|
| class ActionError(ValueError): |
| """Raised when a brain proposes something outside the vocabulary.""" |
|
|
|
|
| @dataclass(frozen=True) |
| class Action: |
| """One step of computer use: exactly one verb, validated on construction. |
| |
| label : click target *by element label* — the preferred form, because it |
| survives window moves that would break raw pixel coordinates |
| x, y : pixel fallback, used only when no label matches |
| text : literal text to type |
| keys : key chord, e.g. ``ctrl+s`` |
| amount : scroll ticks; negative scrolls up |
| seconds : how long to wait |
| reason : the brain's stated rationale — kept for traces, never executed |
| """ |
|
|
| kind: str |
| label: str | None = None |
| x: int | None = None |
| y: int | None = None |
| text: str | None = None |
| keys: str | None = None |
| amount: int = 0 |
| seconds: float = 0.0 |
| reason: str = "" |
|
|
| def __post_init__(self) -> None: |
| if self.kind not in ACTION_KINDS: |
| raise ActionError(f"unknown action {self.kind!r}; expected one of {ACTION_KINDS}") |
| if self.kind == "click": |
| if not self.label and not (self.x is not None and self.y is not None): |
| raise ActionError("click needs a label, or x and y") |
| if (self.x is not None and self.x < 0) or (self.y is not None and self.y < 0): |
| raise ActionError("click coordinates must be non-negative") |
| if self.kind == "type" and not self.text: |
| raise ActionError("type needs non-empty text") |
| if self.kind == "key" and not self.keys: |
| raise ActionError("key needs a chord, e.g. 'ctrl+s'") |
| if self.kind == "scroll" and self.amount == 0: |
| raise ActionError("scroll needs a non-zero amount") |
| if self.kind == "wait" and self.seconds <= 0: |
| raise ActionError("wait needs a positive number of seconds") |
|
|
| def describe(self) -> str: |
| """One-line, human-readable form used in traces and dry-run logs.""" |
| parts: list[str] = [self.kind] |
| if self.label: |
| parts.append(f"label={self.label!r}") |
| if self.x is not None and self.y is not None: |
| parts.append(f"at=({self.x},{self.y})") |
| if self.text is not None: |
| parts.append(f"text={self.text!r}") |
| if self.keys: |
| parts.append(f"keys={self.keys!r}") |
| if self.kind == "scroll": |
| parts.append(f"amount={self.amount}") |
| if self.kind == "wait": |
| parts.append(f"seconds={self.seconds}") |
| if self.reason: |
| parts.append(f"reason={self.reason!r}") |
| return " ".join(parts) |
|
|
| def to_dict(self) -> dict[str, Any]: |
| return { |
| "kind": self.kind, |
| "label": self.label, |
| "x": self.x, |
| "y": self.y, |
| "text": self.text, |
| "keys": self.keys, |
| "amount": self.amount, |
| "seconds": self.seconds, |
| "reason": self.reason, |
| } |
|
|
|
|
| ACTION_MENU: Final[str] = """\ |
| Reply with exactly one JSON object and nothing else. Allowed verbs: |
| |
| {"kind": "click", "label": "<text of the element to click>", "reason": "..."} |
| {"kind": "click", "x": 640, "y": 400, "reason": "..."} // pixels, only if no label fits |
| {"kind": "type", "text": "...", "reason": "..."} |
| {"kind": "key", "keys": "ctrl+s", "reason": "..."} |
| {"kind": "scroll", "amount": -3, "reason": "..."} |
| {"kind": "wait", "seconds": 1.5, "reason": "..."} |
| {"kind": "done", "reason": "why the goal is met"} |
| |
| Rules: one action per reply; prefer a label over guessing pixels; reply "done" |
| as soon as the goal is met; never invent new verbs.""" |
|
|
| _FIELDS: Final[tuple[str, ...]] = ( |
| "label", "x", "y", "text", "keys", "amount", "seconds", "reason", |
| ) |
|
|
|
|
| def parse_action(payload: Mapping[str, Any]) -> Action: |
| """Turn a brain's raw mapping into a validated :class:`Action`. |
| |
| Unknown keys are ignored, so a chatty model cannot crash the loop. An unknown |
| verb or a missing field raises :class:`ActionError`, which the loop records as |
| a failed step *without executing anything*. |
| """ |
| if not isinstance(payload, Mapping): |
| raise ActionError(f"expected a mapping, got {type(payload).__name__}") |
| kind = payload.get("kind") |
| if kind not in ACTION_KINDS: |
| raise ActionError(f"unknown action {kind!r}; expected one of {ACTION_KINDS}") |
| kwargs = {k: payload[k] for k in _FIELDS if k in payload} |
| return Action(kind=str(kind), **kwargs) |
|
|
