Metadata-Version: 2.4
Name: letsautomate
Version: 0.1.0
Summary: Performance-Optimised Windows UI Automation framework for Computer Using Agents
License: MIT License
        
        Copyright (c) 2025 LetsAutomate Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nimesh-mayad/letsautomate
Project-URL: Bug Tracker, https://github.com/nimesh-mayad/letsautomate/issues
Keywords: windows,ui-automation,uia,accessibility,computer-using-agent,rpa,win32,cua
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Provides-Extra: benchmark
Requires-Dist: numpy>=1.24; extra == "benchmark"
Requires-Dist: pandas>=2.0; extra == "benchmark"
Requires-Dist: matplotlib>=3.7; extra == "benchmark"
Requires-Dist: seaborn>=0.12; extra == "benchmark"
Requires-Dist: scipy>=1.10; extra == "benchmark"
Provides-Extra: baselines
Requires-Dist: pywinauto>=0.6; extra == "baselines"
Requires-Dist: uiautomation>=2.0; extra == "baselines"
Requires-Dist: pyautogui>=0.9; extra == "baselines"
Provides-Extra: all
Requires-Dist: letsautomate[benchmark]; extra == "all"
Requires-Dist: letsautomate[baselines]; extra == "all"
Dynamic: license-file

# LetsAutomate

**Performance-optimised Windows UI Automation framework for Computer Using Agents.**

LetsAutomate is a hybrid C++17/Python framework that uses `IUIAutomationCacheRequest` to retrieve all element properties across the entire UI tree in a **single cross-process COM call**, eliminating the per-property IPC overhead that makes existing frameworks (pywinauto, python-uiautomation) slow.

> **Windows only.** Requires Windows 10 (1903+) or Windows 11.

---

## Why LetsAutomate?

| Framework | Perception call (50 elements x 5 props) | IPC calls |
|---|---|---|
| **LetsAutomate** | ~12 ms | **1** (batch cache) |
| pywinauto UIA | ~9,500 ms | 250 |
| python-uiautomation | ~7,000 ms | 250 |
| pywinauto Win32 | ~800 ms | 50+ |
| pyautogui | N/A (cannot enumerate elements) | 0 |

The speedup comes from `IUIAutomationCacheRequest` + `FindAllBuildCache`: one COM round-trip populates a local snapshot store. Subsequent reads have zero IPC overhead until a `StructureChangedEvent` triggers a refresh.

---

## Installation

```
pip install letsautomate
```

> **Requires Windows 10/11.** The native `lacore.pyd` extension links against
> `UIAutomationCore.dll`, `ole32.dll`, and `user32.dll` -- all present on
> every Windows 10/11 installation.

For the benchmark suite and charts:

```
pip install letsautomate[benchmark]
```

To compare against baseline frameworks:

```
pip install letsautomate[baselines]
```

---

## Quick start

```python
import ctypes
from letsautomate import LetsAutomate

# Open Notepad first, then:
hwnd = ctypes.windll.user32.FindWindowW(None, "Untitled - Notepad")

with LetsAutomate() as fw:
    fw.initialise()
    fw.configure_cache(["name", "automation_id", "control_type",
                        "bounding_rect", "is_enabled"])

    # Batch-retrieve all elements in ONE cross-process COM call
    elements = fw.query_elements_cached(hwnd)
    for elem in elements:
        print(elem.name, elem.control_type, elem.bounding_rect)

    # Find and click the File menu
    handle = fw.find_element(hwnd, by="name", value="File")
    fw.execute_action(handle, "click")
```

---

## API reference

### `LetsAutomate`

| Method | Description |
|---|---|
| `initialise()` | Initialise COM, UIAutomation, and the background event thread. |
| `shutdown()` | Clean shutdown -- deregisters all event handlers and releases COM objects. |
| `configure_cache(properties, scope, mode)` | Set which properties to cache and the tree traversal scope. |
| `query_elements_cached(hwnd, scope)` | Batch-retrieve all elements in one IPC call. Returns `list[ElementSnapshot]`. |
| `find_element(hwnd, by, value)` | Find a single element by criterion. Returns `ElementHandle`. |
| `execute_action(element, action, **params)` | Execute a UI action on an element. |
| `subscribe_events(hwnd, event_types, scope, callback)` | Subscribe to UIAutomation push events. |
| `get_benchmark_metrics()` | Return internal diagnostic metrics. |

### `execute_action` -- supported actions

| Action | Description |
|---|---|
| `"click"` | InvokePattern or Win32 mouse click fallback. |
| `"type"` | ValuePattern or Win32 `WM_SETTEXT` fallback. Pass `text="..."`. |
| `"scroll"` | ScrollPattern. Pass `scroll_direction="up"` or `"down"`. |
| `"focus"` | SetFocus() via UIAutomation. |
| `"hover"` | Move cursor to element centre. |
| `"select"` | SelectionItemPattern (for list items, radio buttons). |
| `"expand"` | ExpandCollapsePattern (for tree nodes, combo boxes). Pass `expand=True/False`. |

---

## Running the benchmark suite

```
letsautomate-bench --app notepad --benchmarks all
```

Run charts after benchmarking:

```
letsautomate-charts --benchmarks BM02,BM04
```

Results are written to `letsautomate_results/` in the current directory.
Charts are written to `letsautomate_figures/`.

---

## Running the tests

```
python -m pytest tests/
```

Or without pytest:

```
python tests/test_native_core.py
python tests/test_action_dispatch.py
```

---

## Building from source

If no pre-compiled wheel exists for your Python version, you can build from
source. See [PUBLISHING.md](https://github.com/YOUR_USERNAME/letsautomate/blob/main/PUBLISHING.md)
for the full build guide. Requirements:

- Visual Studio 2022 with "Desktop development with C++" workload
- Windows SDK 10.0.19041+
- x64 Native Tools Command Prompt for VS 2022

---

## Architecture

```
letsautomate/
  letsautomate.py        -- Python API class (LetsAutomate)
  element_handle.py      -- ElementHandle wrapping a live IUIAutomationElement*
  element_snapshot.py    -- ElementSnapshot (cached, immutable, no COM calls)
  exceptions.py          -- UAException hierarchy

native/ (compiled into lacore.pyd)
  NativeCore.cpp         -- COM init, IUIAutomation singleton
  ElementCacheManager.cpp-- IUIAutomationCacheRequest batch retrieval
  EventPerceptionEngine.cpp -- STA background thread, event handlers
  ActionDispatcher.cpp   -- UIA pattern + Win32 fallback action execution
  Win32Core.cpp          -- Win32 API helpers (HWND -> IUIAutomationElement*)
  CPythonInterface.cpp   -- Python C extension entry points
```

---

## License

MIT. See [LICENSE](LICENSE).
