hkblockchaintechnology commited on
Commit
629714e
·
verified ·
1 Parent(s): 9fcc57f

Publish README.md from marimo

Browse files
Files changed (1) hide show
  1. README.md +61 -10
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
- # 217 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,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
- **219 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,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 219 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,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 **219 tests**. 217 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,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 # 217 passed, 2 skipped
361
- TINY_COMPUTER_AGENT_LIVE_TEST=1 pytest tests -q # 219 passed, on a desktop
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 # 219 tests, no display or network needed
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
- - [ ] **Make the 256M VLM choose correctly.** Masking fixed the echo and the latency; the model
1189
- still picks the wrong item from a four-item menu of exact widgets. That is now a question
1190
- about weights, or about a better default (the rule-based planner), not about prompt shape.
 
 
 
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