pctr 0.3.4__tar.gz → 0.4.0__tar.gz

{pctr-0.3.4 → pctr-0.4.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Space-lab515
+Copyright (c) 2026 NTUserDev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{pctr-0.3.4/src/pctr.egg-info → pctr-0.4.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: pctr
-Version: 0.3.4
-Summary: Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
-Author: Space-lab515
+Version: 0.4.0
+Summary: PCTR - Personal Computer Tactile Response. Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
+Author: NTUserDev
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/Space-lab515/pctr
-Project-URL: Repository, https://github.com/Space-lab515/pctr
-Project-URL: Issues, https://github.com/Space-lab515/pctr/issues
+Project-URL: Homepage, https://github.com/NTUserDev/pctr
+Project-URL: Repository, https://github.com/NTUserDev/pctr
+Project-URL: Issues, https://github.com/NTUserDev/pctr/issues
 Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Win32 (MS Windows)
@@ -31,10 +31,18 @@ Provides-Extra: vision
 Requires-Dist: ultralytics>=8.2; extra == "vision"
 Provides-Extra: mcp
 Requires-Dist: mcp>=2; extra == "mcp"
+Provides-Extra: pad
+Requires-Dist: vgamepad>=0.1.0; extra == "pad"
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: all
+Requires-Dist: pctr[mcp,pad,serial,vision]; extra == "all"
 Dynamic: license-file
 
 # pctr
 
+**PCTR — Personal Computer Tactile Response**
+
 Element-based Windows UI Automation CLI for AI agents.
 
 Instead of screenshotting and guessing pixel coordinates, `pctr` finds controls
@@ -46,11 +54,21 @@ mouse and keyboard input. On top of UIA it also offers **OCR**
 (`Windows.Media.Ocr`) and **YOLO-World** open-vocabulary detection for text and
 objects that aren't exposed as controls.
 
+![pctr driving by element name: enumerating windows, mapping virtual desktops, dumping the control tree, filling a field, then reading it back with OCR](docs/demo.gif)
+
+*Driven entirely by pctr itself - list windows, map virtual desktops, dump a
+control tree, `set` a field, read it back with OCR, screenshot it, and YOLO-World
+detect. Recorded with OBS, which pctr also piloted.*
+
 ## Install
 
 ```bash
-pip install pctr
-pip install "pctr[vision]"   # adds ultralytics for `pctr look`
+pip install pctr             # core (UIA + OCR)
+pip install "pctr[vision]"   # + ultralytics, for `pctr look`
+pip install "pctr[mcp]"      # + MCP SDK, for the MCP server
+pip install "pctr[pad]"      # + vgamepad, for `pctr pad` (needs ViGEmBus)
+pip install "pctr[serial]"   # + pyserial, for `pctr hid` / the serial-hid backend
+pip install "pctr[all]"      # everything
 ```
 
 Windows only.
@@ -77,6 +95,18 @@ Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
 `pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
 `pctr_desktop`.
 
+Or run/manage it from the CLI:
+
+```bash
+pctr mcp status                                          # SDK + server state
+pctr mcp start --transport streamable-http --port 8765   # background HTTP server
+pctr mcp restart | pctr mcp stop
+pctr mcp help
+```
+
+`stdio` runs in the foreground (what a client spawns); `sse` / `streamable-http`
+run in the background, reachable at `http://127.0.0.1:8765/mcp` (or `…/sse`).
+
 ## Commands
 
 | Command | What it does |
@@ -97,13 +127,19 @@ Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
 | `pctr move --x N --y N` / `down` / `up` / `hold --ms N` | Raw mouse control (`--direct` for games). |
 | `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
 | `pctr keydown / keyup --key a` / `keyhold --key w --ms 1500` | Hold keyboard keys (`--direct` for games). |
-| `pctr ocr [--title RE]` | OCR the screen/window; list words with boxes. |
-| `pctr ocrfind --text RE` | OCR then list matches with click centers (single words). |
-| `pctr ocrclick --text RE [--nth N]` | OCR then click a word. |
+| `pctr ocr [--title RE] [--lang TAG]` | OCR the screen/window; list words with boxes. |
+| `pctr ocrfind --text RE [--lang TAG]` | OCR then list matches with click centers (single words). |
+| `pctr ocrclick --text RE [--nth N] [--lang TAG]` | OCR then click a word. |
 | `pctr look --for "a dog" [--title RE] [--conf X]` | YOLO-World detect objects by text prompt. |
 | `pctr lookclick --for "a dog" [--nth N]` | Detect then click the top match. |
+| `pctr pad <button\|stick\|trigger\|status>` | Virtual Xbox 360 gamepad via ViGEmBus. |
+| `pctr hid <action> --port COMx` | Serial-HID bridge to a real USB-HID microcontroller. |
+| `pctr mcp <start\|stop\|restart\|status\|help>` | Manage the MCP server (stdio or background http/sse). |
 | `pctr skill [--install]` / `pctr setup` | Print/install the agent skill + an AGENTS.md section. |
 
+Global flags: `--json` (machine-readable output) and `--file FILE` (run a batch
+of commands from a file).
+
 Common filters: `--title` (regex), `--name` (regex), `--control-type`
 (`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
 
@@ -118,6 +154,33 @@ pctr click --title "Notepad" --name "^File$"
 pctr set   --title "Notepad" --name "Text Editor" --text "hello"
 ```
 
+## JSON output
+
+Add `--json` (global, or per-command) for machine-readable output from
+`windows`, `tree`, `find`, `ocr`, `ocrfind`, `look`, and `desktop`:
+
+```bash
+pctr windows --json
+# [{"hwnd":1234,"pid":5678,"title":"Untitled - Notepad"}, ...]
+
+pctr desktop list --json
+# [{"index":0,"guid":"ae37…","current":true,"windows":11}, ...]
+
+pctr look --for "a car" --json
+# [{"label":"a car","conf":0.86,"x":512,"y":300,"box":[400,220,620,380]}, ...]
+```
+
+Progress and warnings go to stderr, so stdout stays valid JSON.
+
+## Batch files
+
+```bash
+pctr --file script.txt          # one command per line; # comments and blanks skipped
+pctr --json --file script.txt   # --json applies to every line
+```
+
+Stops on the first failing line and reports its line number.
+
 ## Virtual desktops
 
 ```bash
@@ -137,6 +200,49 @@ pctr desktop move-window --title RE --to N
 - **`move-window` is blocked on Windows 11** (third-party `MoveWindowToDesktop`
   returns `Access denied`); it works on Windows 10.
 
+## Raw input backends
+
+The OS flags `SendInput` events as injected, so anything built on user32 is
+detectable in principle. `pctr` can route raw mouse/keyboard through a different
+backend with `--backend`:
+
+| Backend | How | Detectable? |
+|---|---|---|
+| `pyautogui` (default / `sendinput`) | user32 `SendInput`, virtual keys | yes (`injected` flag) |
+| `pydirectinput` (or `--direct`) | `SendInput` with **scancodes** — better for DirectInput games | yes |
+| `serial-hid` | a **microcontroller presenting real USB HID** over serial | no — it *is* real hardware |
+
+```bash
+pctr move --backend pydirectinput --x 800 --y 400
+pctr keyhold --key w --ms 400 --backend pydirectinput
+pctr type --text "hi" --backend serial-hid --port COM5   # needs a board
+```
+
+Applies to `move` / `down` / `up` / `hold` / `keydown` / `keyup` / `keyhold` /
+`hotkey` / `drag` / `type` / `desktop`.
+
+### Gamepad
+
+```bash
+pip install "pctr[pad]"     # + the ViGEmBus driver
+pctr pad button  --name A --ms 150
+pctr pad button  --name DPAD_UP --ms 100
+pctr pad stick   --x 1.0 --y -0.5 --ms 400
+pctr pad trigger --right 1.0 --ms 300
+```
+
+### Serial-HID bridge
+
+Firmware protocol, newline-terminated ASCII:
+`MOVE x y` · `CLICK b` · `DOWN b` · `UP b` · `KEY k DOWN|UP` · `WRITE text` · `HOTKEY a+b`
+
+```bash
+pip install "pctr[serial]"
+pctr hid ports                                  # list COM ports
+pctr hid move --x 500 --y 300 --port COM5
+pctr hid type --text "hello" --port COM5
+```
+
 ## Exit codes
 
 - `0` success, `1` no match / window not found, `2` usage/validation error.

{pctr-0.3.4 → pctr-0.4.0}/README.md

@@ -1,5 +1,7 @@
 # pctr
 
+**PCTR — Personal Computer Tactile Response**
+
 Element-based Windows UI Automation CLI for AI agents.
 
 Instead of screenshotting and guessing pixel coordinates, `pctr` finds controls
@@ -11,11 +13,21 @@ mouse and keyboard input. On top of UIA it also offers **OCR**
 (`Windows.Media.Ocr`) and **YOLO-World** open-vocabulary detection for text and
 objects that aren't exposed as controls.
 
+![pctr driving by element name: enumerating windows, mapping virtual desktops, dumping the control tree, filling a field, then reading it back with OCR](docs/demo.gif)
+
+*Driven entirely by pctr itself - list windows, map virtual desktops, dump a
+control tree, `set` a field, read it back with OCR, screenshot it, and YOLO-World
+detect. Recorded with OBS, which pctr also piloted.*
+
 ## Install
 
 ```bash
-pip install pctr
-pip install "pctr[vision]"   # adds ultralytics for `pctr look`
+pip install pctr             # core (UIA + OCR)
+pip install "pctr[vision]"   # + ultralytics, for `pctr look`
+pip install "pctr[mcp]"      # + MCP SDK, for the MCP server
+pip install "pctr[pad]"      # + vgamepad, for `pctr pad` (needs ViGEmBus)
+pip install "pctr[serial]"   # + pyserial, for `pctr hid` / the serial-hid backend
+pip install "pctr[all]"      # everything
 ```
 
 Windows only.
@@ -42,6 +54,18 @@ Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
 `pctr_shot`, `pctr_ocr`, `pctr_ocrfind`, `pctr_ocrclick`, `pctr_look`,
 `pctr_desktop`.
 
+Or run/manage it from the CLI:
+
+```bash
+pctr mcp status                                          # SDK + server state
+pctr mcp start --transport streamable-http --port 8765   # background HTTP server
+pctr mcp restart | pctr mcp stop
+pctr mcp help
+```
+
+`stdio` runs in the foreground (what a client spawns); `sse` / `streamable-http`
+run in the background, reachable at `http://127.0.0.1:8765/mcp` (or `…/sse`).
+
 ## Commands
 
 | Command | What it does |
@@ -62,13 +86,19 @@ Tools exposed: `pctr_windows`, `pctr_tree`, `pctr_find`, `pctr_click`,
 | `pctr move --x N --y N` / `down` / `up` / `hold --ms N` | Raw mouse control (`--direct` for games). |
 | `pctr drag --start x,y --end x,y [--duration S]` | Drag between two points. |
 | `pctr keydown / keyup --key a` / `keyhold --key w --ms 1500` | Hold keyboard keys (`--direct` for games). |
-| `pctr ocr [--title RE]` | OCR the screen/window; list words with boxes. |
-| `pctr ocrfind --text RE` | OCR then list matches with click centers (single words). |
-| `pctr ocrclick --text RE [--nth N]` | OCR then click a word. |
+| `pctr ocr [--title RE] [--lang TAG]` | OCR the screen/window; list words with boxes. |
+| `pctr ocrfind --text RE [--lang TAG]` | OCR then list matches with click centers (single words). |
+| `pctr ocrclick --text RE [--nth N] [--lang TAG]` | OCR then click a word. |
 | `pctr look --for "a dog" [--title RE] [--conf X]` | YOLO-World detect objects by text prompt. |
 | `pctr lookclick --for "a dog" [--nth N]` | Detect then click the top match. |
+| `pctr pad <button\|stick\|trigger\|status>` | Virtual Xbox 360 gamepad via ViGEmBus. |
+| `pctr hid <action> --port COMx` | Serial-HID bridge to a real USB-HID microcontroller. |
+| `pctr mcp <start\|stop\|restart\|status\|help>` | Manage the MCP server (stdio or background http/sse). |
 | `pctr skill [--install]` / `pctr setup` | Print/install the agent skill + an AGENTS.md section. |
 
+Global flags: `--json` (machine-readable output) and `--file FILE` (run a batch
+of commands from a file).
+
 Common filters: `--title` (regex), `--name` (regex), `--control-type`
 (`Button`, `Edit`, `Pane`, `MenuItem`, …), `--auto-id`, `--nth`, `--process`.
 
@@ -83,6 +113,33 @@ pctr click --title "Notepad" --name "^File$"
 pctr set   --title "Notepad" --name "Text Editor" --text "hello"
 ```
 
+## JSON output
+
+Add `--json` (global, or per-command) for machine-readable output from
+`windows`, `tree`, `find`, `ocr`, `ocrfind`, `look`, and `desktop`:
+
+```bash
+pctr windows --json
+# [{"hwnd":1234,"pid":5678,"title":"Untitled - Notepad"}, ...]
+
+pctr desktop list --json
+# [{"index":0,"guid":"ae37…","current":true,"windows":11}, ...]
+
+pctr look --for "a car" --json
+# [{"label":"a car","conf":0.86,"x":512,"y":300,"box":[400,220,620,380]}, ...]
+```
+
+Progress and warnings go to stderr, so stdout stays valid JSON.
+
+## Batch files
+
+```bash
+pctr --file script.txt          # one command per line; # comments and blanks skipped
+pctr --json --file script.txt   # --json applies to every line
+```
+
+Stops on the first failing line and reports its line number.
+
 ## Virtual desktops
 
 ```bash
@@ -102,6 +159,49 @@ pctr desktop move-window --title RE --to N
 - **`move-window` is blocked on Windows 11** (third-party `MoveWindowToDesktop`
   returns `Access denied`); it works on Windows 10.
 
+## Raw input backends
+
+The OS flags `SendInput` events as injected, so anything built on user32 is
+detectable in principle. `pctr` can route raw mouse/keyboard through a different
+backend with `--backend`:
+
+| Backend | How | Detectable? |
+|---|---|---|
+| `pyautogui` (default / `sendinput`) | user32 `SendInput`, virtual keys | yes (`injected` flag) |
+| `pydirectinput` (or `--direct`) | `SendInput` with **scancodes** — better for DirectInput games | yes |
+| `serial-hid` | a **microcontroller presenting real USB HID** over serial | no — it *is* real hardware |
+
+```bash
+pctr move --backend pydirectinput --x 800 --y 400
+pctr keyhold --key w --ms 400 --backend pydirectinput
+pctr type --text "hi" --backend serial-hid --port COM5   # needs a board
+```
+
+Applies to `move` / `down` / `up` / `hold` / `keydown` / `keyup` / `keyhold` /
+`hotkey` / `drag` / `type` / `desktop`.
+
+### Gamepad
+
+```bash
+pip install "pctr[pad]"     # + the ViGEmBus driver
+pctr pad button  --name A --ms 150
+pctr pad button  --name DPAD_UP --ms 100
+pctr pad stick   --x 1.0 --y -0.5 --ms 400
+pctr pad trigger --right 1.0 --ms 300
+```
+
+### Serial-HID bridge
+
+Firmware protocol, newline-terminated ASCII:
+`MOVE x y` · `CLICK b` · `DOWN b` · `UP b` · `KEY k DOWN|UP` · `WRITE text` · `HOTKEY a+b`
+
+```bash
+pip install "pctr[serial]"
+pctr hid ports                                  # list COM ports
+pctr hid move --x 500 --y 300 --port COM5
+pctr hid type --text "hello" --port COM5
+```
+
 ## Exit codes
 
 - `0` success, `1` no match / window not found, `2` usage/validation error.

{pctr-0.3.4 → pctr-0.4.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pctr"
-version = "0.3.4"
-description = "Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates."
+version = "0.4.0"
+description = "PCTR - Personal Computer Tactile Response. Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
-authors = [{ name = "Space-lab515" }]
+authors = [{ name = "NTUserDev" }]
 keywords = ["automation", "windows", "uia", "pywinauto", "desktop", "agent", "computer-use", "rpa"]
 classifiers = [
   "Development Status :: 4 - Beta",
@@ -35,18 +35,21 @@ dependencies = [
 [project.optional-dependencies]
 vision = ["ultralytics>=8.2"]
 mcp = ["mcp>=2"]
+pad = ["vgamepad>=0.1.0"]
+serial = ["pyserial>=3.5"]
+all = ["pctr[vision,mcp,pad,serial]"]
 
 [project.scripts]
 pctr = "pctr.cli:main"
 pctr-mcp = "pctr.mcp_server:main"
 
 [project.urls]
-Homepage = "https://github.com/Space-lab515/pctr"
-Repository = "https://github.com/Space-lab515/pctr"
-Issues = "https://github.com/Space-lab515/pctr/issues"
+Homepage = "https://github.com/NTUserDev/pctr"
+Repository = "https://github.com/NTUserDev/pctr"
+Issues = "https://github.com/NTUserDev/pctr/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]
 
 [tool.setuptools.package-data]
-pctr = ["data/*.md"]
+pctr = ["data/*.md", "py.typed"]

pctr-0.4.0/src/pctr/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"