Publish README.md from marimo
Browse files
README.md
CHANGED
|
@@ -90,7 +90,7 @@ X server. First the suite, headless:
|
|
| 90 |
```bash
|
| 91 |
python -m pip install -e ".[desktop,ocr,dev]"
|
| 92 |
pytest tests -q
|
| 93 |
-
#
|
| 94 |
```
|
| 95 |
|
| 96 |
The two skips are the live-desktop tests. Give them a display and they run for real:
|
|
@@ -262,7 +262,7 @@ open problem: it is reliable on a clean screenshot and unreliable on a busy live
|
|
| 262 |
`warning: no text was found on screen, so the index is 96 numbered grid cells and the
|
| 263 |
agent is choosing blind` — instead of silently guessing.
|
| 264 |
|
| 265 |
-
**
|
| 266 |
that click a real button.
|
| 267 |
|
| 268 |
## Verified on real Windows
|
|
@@ -304,7 +304,7 @@ the harness itself, installed into site-packages
|
|
| 304 |
|
| 305 |
None of the three failures in the first row is a harness defect: two are
|
| 306 |
`ModuleNotFoundError: numpy` and the third is the guard bug documented below. With the
|
| 307 |
-
OCR engine installed, the same suite exits **0**. (Those Windows counts predate `trace.py`; the harness suite has since grown to
|
| 308 |
|
| 309 |
**The emulated-OCR caveat.** onnxruntime requires AVX2, and QEMU's software emulation of
|
| 310 |
AVX2 is roughly two orders of magnitude slower than native. A suite that finishes in 17
|
|
@@ -330,7 +330,7 @@ exactly the kind of thing that only surfaces on a machine without an OCR engine.
|
|
| 330 |
|
| 331 |
## The test suite, in full
|
| 332 |
|
| 333 |
-
`pytest tests` collects **
|
| 334 |
weights. The last 2 are the opt-in live-desktop tests, skipped unless
|
| 335 |
`TINY_COMPUTER_AGENT_LIVE_TEST=1`.
|
| 336 |
|
|
@@ -357,8 +357,8 @@ weights. The last 2 are the opt-in live-desktop tests, skipped unless
|
|
| 357 |
| `tests/test_live_desktop.py` | 2 | **needs a display, opt-in**: OCR finds a real button at the pixels it was drawn at, and a real click makes the app react |
|
| 358 |
|
| 359 |
```bash
|
| 360 |
-
pytest tests -q #
|
| 361 |
-
TINY_COMPUTER_AGENT_LIVE_TEST=1 pytest tests -q #
|
| 362 |
```
|
| 363 |
|
| 364 |
## Install
|
|
@@ -367,7 +367,7 @@ TINY_COMPUTER_AGENT_LIVE_TEST=1 pytest tests -q # 219 passed, on a desktop
|
|
| 367 |
pip install -e ".[ocr]" # labels from pixels (RapidOCR: no system binary)
|
| 368 |
pip install -e ".[desktop,ocr]" # + real capture and real input
|
| 369 |
pip install -e ".[vision,ocr]" # + the tiny model brains
|
| 370 |
-
pytest #
|
| 371 |
```
|
| 372 |
|
| 373 |
The accessibility detector needs system packages rather than an extra:
|
|
@@ -481,6 +481,7 @@ this: an answer file with non-canonical XML namespaces is **silently ignored** b
|
|
| 481 |
| `accessibility.py` | The accessibility tree: `AtspiReader` and `AtspiDetector`, roles and real extents |
|
| 482 |
| `showcase.py` | The capability gallery: one real screenshot per capability, checked against the public API |
|
| 483 |
| `measure_vlm.py` | Measures the four ways to ask a model, on a real screen, and prints the table |
|
|
|
|
| 484 |
|
| 485 |
## The marimo console
|
| 486 |
|
|
@@ -533,6 +534,53 @@ reads `last action: Save` afterwards, and the app wrote `Save` to its marker fil
|
|
| 533 |
on Windows keeps using OCR. Tk barely publishes a tree and a canvas publishes none,
|
| 534 |
which is why this is a detector and not a replacement.
|
| 535 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 536 |
## Capability gallery
|
| 537 |
|
| 538 |
**68 capabilities, one screenshot each - and every one of the 141 public callables in the package (functions, methods, classes and protocols) appears in at least one of them**, together with 6 of its public constants.
|
|
@@ -1185,9 +1233,12 @@ when no verifier is given.
|
|
| 1185 |
[asking a tiny model in four ways](#asking-a-tiny-model-in-four-ways-measured)
|
| 1186 |
- [x] The marimo console: live screen preview, action log, pause / resume / step
|
| 1187 |
- [x] An accessibility-tree detector on Linux (AT-SPI), driving a real click with no OCR
|
| 1188 |
-
- [
|
| 1189 |
-
|
| 1190 |
-
|
|
|
|
|
|
|
|
|
|
| 1191 |
- [ ] **UI Automation** (Windows) for the accessibility detector. The interface is here and
|
| 1192 |
`accessibility_available("uia")` reports it as not implemented rather than pretending.
|
| 1193 |
- [ ] Windows run of the *live desktop* test: the workflow is committed, but it needs a
|
|
|
|
| 90 |
```bash
|
| 91 |
python -m pip install -e ".[desktop,ocr,dev]"
|
| 92 |
pytest tests -q
|
| 93 |
+
# 227 passed, 2 skipped in 18.7s
|
| 94 |
```
|
| 95 |
|
| 96 |
The two skips are the live-desktop tests. Give them a display and they run for real:
|
|
|
|
| 262 |
`warning: no text was found on screen, so the index is 96 numbered grid cells and the
|
| 263 |
agent is choosing blind` — instead of silently guessing.
|
| 264 |
|
| 265 |
+
**229 tests pass**, including real OCR over a real image and (opt-in) live-desktop tests
|
| 266 |
that click a real button.
|
| 267 |
|
| 268 |
## Verified on real Windows
|
|
|
|
| 304 |
|
| 305 |
None of the three failures in the first row is a harness defect: two are
|
| 306 |
`ModuleNotFoundError: numpy` and the third is the guard bug documented below. With the
|
| 307 |
+
OCR engine installed, the same suite exits **0**. (Those Windows counts predate `trace.py`; the harness suite has since grown to 229 tests.)
|
| 308 |
|
| 309 |
**The emulated-OCR caveat.** onnxruntime requires AVX2, and QEMU's software emulation of
|
| 310 |
AVX2 is roughly two orders of magnitude slower than native. A suite that finishes in 17
|
|
|
|
| 330 |
|
| 331 |
## The test suite, in full
|
| 332 |
|
| 333 |
+
`pytest tests` collects **229 tests**. 227 run headless — no display, no network, no
|
| 334 |
weights. The last 2 are the opt-in live-desktop tests, skipped unless
|
| 335 |
`TINY_COMPUTER_AGENT_LIVE_TEST=1`.
|
| 336 |
|
|
|
|
| 357 |
| `tests/test_live_desktop.py` | 2 | **needs a display, opt-in**: OCR finds a real button at the pixels it was drawn at, and a real click makes the app react |
|
| 358 |
|
| 359 |
```bash
|
| 360 |
+
pytest tests -q # 227 passed, 2 skipped
|
| 361 |
+
TINY_COMPUTER_AGENT_LIVE_TEST=1 pytest tests -q # 229 passed, on a desktop
|
| 362 |
```
|
| 363 |
|
| 364 |
## Install
|
|
|
|
| 367 |
pip install -e ".[ocr]" # labels from pixels (RapidOCR: no system binary)
|
| 368 |
pip install -e ".[desktop,ocr]" # + real capture and real input
|
| 369 |
pip install -e ".[vision,ocr]" # + the tiny model brains
|
| 370 |
+
pytest # 229 tests, no display or network needed
|
| 371 |
```
|
| 372 |
|
| 373 |
The accessibility detector needs system packages rather than an extra:
|
|
|
|
| 481 |
| `accessibility.py` | The accessibility tree: `AtspiReader` and `AtspiDetector`, roles and real extents |
|
| 482 |
| `showcase.py` | The capability gallery: one real screenshot per capability, checked against the public API |
|
| 483 |
| `measure_vlm.py` | Measures the four ways to ask a model, on a real screen, and prints the table |
|
| 484 |
+
| `evaluate_daily.py` | A day's tasks against a real app, verified by the app's own log |
|
| 485 |
|
| 486 |
## The marimo console
|
| 487 |
|
|
|
|
| 534 |
on Windows keeps using OCR. Tk barely publishes a tree and a canvas publishes none,
|
| 535 |
which is why this is a detector and not a replacement.
|
| 536 |
|
| 537 |
+
## Can it do a day's work?
|
| 538 |
+
|
| 539 |
+
The honest way to answer "could this replace a person at a PC?" is to give it a
|
| 540 |
+
person's tasks and check the result against **the application's own record**, not the
|
| 541 |
+
agent's opinion of itself. Eleven of them, on a real GTK desktop with the real mouse:
|
| 542 |
+
|
| 543 |
+
```
|
| 544 |
+
button yes 0.7 Click Save
|
| 545 |
+
right-button yes 0.4 Click Cancel, not the button next to it
|
| 546 |
+
type yes 1.8 Type a new file name and save
|
| 547 |
+
shortcut yes 0.7 Press Ctrl+S
|
| 548 |
+
menu yes 0.7 Open the File menu and choose Save As
|
| 549 |
+
scroll yes 1.5 Scroll the list and pick a row
|
| 550 |
+
second-window yes 0.7 Open Settings and press Apply there
|
| 551 |
+
see yes 0.1 Read what the window says
|
| 552 |
+
verify yes 0.7 Check the save actually happened
|
| 553 |
+
refuse yes 0.1 Do not press the Terminal button
|
| 554 |
+
kill-switch yes 0.1 Stop a live run mid-plan
|
| 555 |
+
```
|
| 556 |
+
|
| 557 |
+
Run it yourself with `python evaluate_daily.py` (`--only menu` for one task).
|
| 558 |
+
|
| 559 |
+
**What that number does and does not mean.** The first run of this suite scored
|
| 560 |
+
**5/11**, and the failures were not the model. A coordinate bug in the detector
|
| 561 |
+
*chain* was shifting every accessibility click by the capture's scale factor:
|
| 562 |
+
`--detector best` wraps the tree detector inside `AutoDetector`, which reported
|
| 563 |
+
"frame coordinates" for elements that were already screen pixels, so `IndexedScreen`
|
| 564 |
+
re-mapped them through the downscale and the click landed beside the button. Two more
|
| 565 |
+
real gaps surfaced with it - an unnamed GTK list row was invisible to the index (so
|
| 566 |
+
nothing in a list could be clicked at all), and two GTK instances sharing an
|
| 567 |
+
application id made the second launch silently do nothing. All three are fixed and
|
| 568 |
+
pinned by tests.
|
| 569 |
+
|
| 570 |
+
So the machine half works: it can see, decide, act and verify a day's operations, and
|
| 571 |
+
it refuses the dangerous ones. What this suite deliberately does **not** measure is
|
| 572 |
+
*choosing* the actions - nine of the eleven tasks were driven by a scripted action
|
| 573 |
+
list, because that is what isolates the harness from the brain. Choosing is measured
|
| 574 |
+
in [asking a tiny model in four ways](#asking-a-tiny-model-in-four-ways-measured):
|
| 575 |
+
4/4 goals right for a 0.5B text planner over the accessibility index in `rank` mode,
|
| 576 |
+
and 1-2/4 for a 256M VLM.
|
| 577 |
+
|
| 578 |
+
Caveats, stated plainly: this is a Linux GTK desktop under Xvfb with **no window
|
| 579 |
+
manager** (so the keyboard tasks had to move the pointer into the window first,
|
| 580 |
+
because X without a manager focuses by pointer); Windows was not exercised; the tasks
|
| 581 |
+
are single-application with no overlapping windows, no animations and no network; and
|
| 582 |
+
eleven tasks are a sample, not a survey.
|
| 583 |
+
|
| 584 |
## Capability gallery
|
| 585 |
|
| 586 |
**68 capabilities, one screenshot each - and every one of the 141 public callables in the package (functions, methods, classes and protocols) appears in at least one of them**, together with 6 of its public constants.
|
|
|
|
| 1233 |
[asking a tiny model in four ways](#asking-a-tiny-model-in-four-ways-measured)
|
| 1234 |
- [x] The marimo console: live screen preview, action log, pause / resume / step
|
| 1235 |
- [x] An accessibility-tree detector on Linux (AT-SPI), driving a real click with no OCR
|
| 1236 |
+
- [x] Make a tiny model choose correctly: a 0.5B text planner over the accessibility index in
|
| 1237 |
+
`rank` mode gets **4/4** goals right in 0.9s. A 256M **vision** model does not (1-2/4) -
|
| 1238 |
+
it is below the threshold, which is why the rule-free planner is still the default
|
| 1239 |
+
- [x] A daily-usage evaluation: 11 tasks (menu, scroll, typing, shortcut, second window,
|
| 1240 |
+
verify, refuse, kill switch) against a real GTK app, checked against the application's
|
| 1241 |
+
own log - see [can it do a day's work](#can-it-do-a-days-work)
|
| 1242 |
- [ ] **UI Automation** (Windows) for the accessibility detector. The interface is here and
|
| 1243 |
`accessibility_available("uia")` reports it as not implemented rather than pretending.
|
| 1244 |
- [ ] Windows run of the *live desktop* test: the workflow is committed, but it needs a
|