Metadata-Version: 2.4
Name: human-movement
Version: 0.1.6
Summary: Personalized, local human movement and input for computer-use applications
Keywords: mouse,keyboard,human-computer-interaction,personalization
Author: Karim Galal
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Dist: filelock>=3.16
Requires-Dist: platformdirs>=4.3
Requires-Dist: human-movement-bench==0.1.2 ; extra == 'benchmark'
Requires-Dist: human-movement-research==0.1.1 ; extra == 'research'
Maintainer: Karim Galal
Requires-Python: >=3.12
Provides-Extra: benchmark
Provides-Extra: research
Description-Content-Type: text/markdown

# Human Movement

Personalized cursor motion and input timing for existing computer-use applications. Created and maintained solely by **Karim Galal**.

The calling application supplies targets and actions. The SDK supplies movement and timing. Runtime requires no LLM, agent, API key or network service.

Version 0.1.6 improves generation speed while preserving seeded trajectories and timing, fixes held-key ownership and paused capture, and preserves calibrated movement timing during everyday recording.

## Install

Requires Python 3.12 or newer. Native desktop execution and recording currently support **Windows**. Pure trajectory/event generation and custom backends can be used on other operating systems.

```sh
pip install human-movement
```

With uv:

```sh
uv add human-movement
```

## Use

```python
from human_movement import HumanInput

with HumanInput() as human:
    human.move_to(900, 500)
    human.click()
    human.type_text("Hello world — café, 中文, 🙂")
    human.scroll(dy=3)
    human.drag_to(1200, 700)
```

The first construction opens a local calibration lab if no usable profile exists. Press Start and follow approximately five minutes of pointing, dragging, scrolling and typing. Later instances load the same Windows account profile automatically across projects. Importing the package is passive. Explicit calibration:

```sh
human-movement calibrate
human-movement doctor
```

Profiles use the current Windows account SID, a versioned JSON schema, process locking, atomic writes and a backup. They live under `%LOCALAPPDATA%/HumanMovement/profiles/<account-key>/profile.json`. No file argument is required. Applications sharing an account among several people can provide `user_id="person-2"`.

Five minutes provides an initial fit with coverage metadata. It does not fully characterize every behavior. An application can explicitly choose `profile="standard", setup="never"` to avoid automatic setup.

## Actions and coordinates

Supports movement, prescribed waypoints, clicks, double-clicks, button holds, dragging, fractional scrolling, Unicode text, key holds and shortcuts:

```python
human.move_along([(300, 200), (400, 250), (500, 250)], corridor=8)
human.double_click()
human.hotkey("ctrl", "shift", "s")
with human.hold("ctrl"):
    human.click()
```

Inside `hold("ctrl")`, use `press("a")` for Ctrl+A. A shortcut that redundantly presses an SDK-held key is rejected before sending input, preserving the outer hold.

Coordinates are physical virtual-desktop pixels, including negative monitor origins. `client_to_screen(hwnd, x, y)` and `screen_to_client` handle native client coordinates and display scaling. Browser CSS coordinates additionally depend on viewport placement and zoom.

Scroll values are wheel detents, positive down/right. The SDK preserves requested text and endpoints, while the receiving application determines how input is interpreted. The caller supplies focus and targets. An interactive desktop and suitable Windows integrity level are required for execution.

Physical **F8** cancels execution. Physical mouse or keyboard activity cancels by default. Context exit and errors release SDK-held inputs. The context manager is recommended.

## Pure generation and custom backends

```python
from human_movement import HumanInput, generate_events, generate_trajectory
from human_movement.backends.base import MemoryBackend

path = generate_trajectory((10, 20), (900, 500), seed=42)
events = generate_events("type_text", text="Exact text", seed=42)

with HumanInput(profile="standard", setup="never",
                backend=MemoryBackend(), realtime=False) as human:
    human.move_to(900, 500)
```

Generation does not open windows, download models, sleep or send input. Missing or invalid neural checkpoints fall back to the analytical engine with a recorded reason. No validated neural checkpoint is bundled.

## Recording and privacy

```sh
human-movement watch ui
human-movement watch status
human-movement watch stop
```

Opening the recorder is passive. Press Start recording to collect content-free input timing locally. Stop, F8, or closing the window ends capture and saves updates. The continuous recorder checkpoints every minute, pauses during calibration, and stops at a 512 MB raw-data cap. It does not install a startup service.

Outside the lab, typed characters, key codes, clipboard data, screenshots and window titles are discarded. Retained observations contain timing, local press IDs, broad key categories and pointer coordinates. Profiles and recordings remain local. Raw recordings can be exported/deleted through `human-movement recordings`.

`NativeWindowScrollRecorder(hwnd, on_event=callback)` observes vertical/horizontal wheel messages in a window owned by the calling application, on its UI thread. `inspect_scroll_capabilities()` reports supported observation paths. Precision Touchpad gestures inside other applications may bypass the global mouse hook; no universal passive native browser-gesture recorder is claimed. Native/window/browser observations retain distinct provenance and are not double counted.

Minimal Python installations without Tk can still use the browser calibration lab; the native scroll pane is unavailable in that configuration.

## Optional packages

```sh
pip install "human-movement[benchmark]"
pip install "human-movement[research]"
```

The separately versioned evaluator provides trace validation, a local instrumented website, detector controls and reproducible metrics. The research package provides optional PyTorch diffusion training/export. Core input needs only `filelock` and `platformdirs`.

Reported personal mouse fit indices are exploratory comparisons on a single participant. They are not probabilities of being human, website acceptance guarantees or population validation. Detector-based overall scores remain withheld until independent data, controls and functional gates are satisfied. macOS, X11 and Wayland native execution remain future ports; multi-monitor hardware validation and broader behavioral evaluation remain outstanding.

## Development

```sh
uv sync --all-packages --all-extras
uv run pytest
uv run ruff check src packages tests tools
uv run mypy src/human_movement
uv build --all-packages --no-sources
```

MIT licensed. Karim Galal is the sole contributor and maintainer. Third-party dependencies, datasets and research retain their own attribution and licenses.
