Metadata-Version: 2.4
Name: human-input-kit
Version: 0.2.6
Summary: Human-like Playwright mouse, scroll, and typing — Bezier warmup with deterministic seeds. CLI: human-input.
Project-URL: Homepage, https://github.com/human-input-kit/human-input-kit
Project-URL: Documentation, https://github.com/human-input-kit/human-input-kit#readme
Project-URL: Repository, https://github.com/human-input-kit/human-input-kit
Project-URL: Issues, https://github.com/human-input-kit/human-input-kit/issues
Author: human-input-kit contributors
License-Expression: MIT
License-File: LICENSE
Keywords: behavior-replay,bezier-curve,bot-cadence,bot-detection,gesture-recording,human-behavior,human-like-mouse,idle-jitter,interaction-polish,mouse-movement,multilogin-warmup,playwright-input,playwright-scroll,playwright-warmup,scroll-simulation,typing-simulation,warmup-script
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: playwright>=1.40
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: mlx
Description-Content-Type: text/markdown

# human-input-kit

**Human-like Playwright mouse & scroll** — Bezier paths, typing delays, and warmup recipes with deterministic seeds.

[![PyPI version](https://img.shields.io/pypi/v/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
[![Python versions](https://img.shields.io/pypi/pyversions/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)
[![License: MIT](https://img.shields.io/pypi/l/human-input-kit.svg)](https://pypi.org/project/human-input-kit/)

```bash
pip install human-input-kit
human-input --help
```

CLI: **`human-input`** · Python **3.10+** · optional **`[mlx]`** for Launcher helpers

> **Partner (optional):** Warmup pays off inside **isolated MLX profiles** (proxy + fingerprint matched). [Multilogin X](https://multilogin.com?a_aid=saas) — codes `SAAS50` (browser) / `MIN50` (cloud phone) on eligible new purchases. Local demos need no MLX account. [Affiliate disclosure](docs/AFFILIATE.md) · [Multilogin promo codes](https://anti-detect.github.io/).

Human-like **mouse**, **scroll**, and **typing** helpers for Playwright — Bezier paths, variable delays, idle jitter, and gesture record/replay.

## Problem

Raw `page.click()` and `page.keyboard.type()` bursts look mechanical. Warmup workflows need curved mouse paths, uneven scroll cadence, and typing pauses. Teams reinvent these snippets in every scraper.

`human-input-kit` packages the primitives and a small CLI for demo, record, and replay flows.

## Install

```bash
pip install human-input-kit
playwright install chromium
```

Development:

```bash
pip install human-input-kit[dev]
```

![Warmup demo](docs/assets/demo.gif)

> Placeholder: add a screen recording at `docs/assets/demo.gif` (not shipped in the wheel).

## Quick start

```bash
# Reproducible motion (default seed 42)
human-input --seed 42 demo-scroll --url https://news.ycombinator.com
human-input record --duration 30 -o gestures.json
human-input replay gestures.json   # validates gesture JSON schema first

# Runnable warmup example
python examples/demo_warmup.py --seed 42

# Documented recipes (deterministic with --seed)
python recipes/scroll_news.py --seed 42
python recipes/youtube_idle.py --seed 42 --seconds 30 --headed
```

**Sync Playwright API** (default package exports):

```python
from human_input_kit import (
    bezier_mouse_path,
    human_type,
    idle_jitter,
    move_mouse_along,
    random_scroll,
    seed_rng,
)

seed_rng(42)
path = bezier_mouse_path((100, 100), (500, 300))
move_mouse_along(page, path)          # sync Page
random_scroll(page, bursts=4)
idle_jitter(page)
human_type(page, "input[name='q']", "playwright warmup")
```

**Async Playwright API** (`human_input_kit.async_`):

```python
from human_input_kit import seed_rng
from human_input_kit import async_ as human_async

seed_rng(42)
path = human_async.bezier_mouse_path((100, 100), (500, 300))
await human_async.move_mouse_along(page, path)
await human_async.random_scroll(page, bursts=4)
```

See `examples/demo_warmup.py` for a full async script.

### Recipes

Copy-paste scripts in [`recipes/`](recipes/) for common warmup patterns. Each accepts `--seed` so demo motion is reproducible in CI and screen recordings.

| Recipe | Command | Behavior |
|--------|---------|----------|
| News scroll | `python recipes/scroll_news.py --seed 42` | Bezier drift → scroll bursts → idle jitter on a news feed |
| YouTube idle | `python recipes/youtube_idle.py --seed 42 --headed` | Idle micro-moves + rare scroll on `youtube.com` |

Options: `--url`, `--headed` (both); `--bursts` (scroll_news); `--seconds` (youtube_idle).

## MLX warmup (single profile)

`human-input-kit` does **not** bundle MLX or Launcher clients. For one-off MLX profile warmup, follow the **cdp-connect-kit** peer pattern:

```bash
pip install human-input-kit
pip install cdp-connect-kit[mlx]   # peer dependency — not required by human-input-kit
playwright install chromium

export MLX_TOKEN=your_bearer_token
export MLX_FOLDER_ID=your-folder-uuid

# Pseudocode demo with TODO markers for Launcher start/stop:
python examples/mlx_warmup_demo.py --profile-id PROFILE_UUID

# Or warmup an already-started profile (CDP_URL from Launcher):
CDP_URL=http://127.0.0.1:55513 python examples/mlx_warmup_demo.py --profile-id PROFILE_UUID
```

`examples/mlx_warmup_demo.py` documents: Launcher start → `connect_over_cdp` → Bezier scroll/jitter warmup → Launcher stop. Set `HUMAN_INPUT_KIT_MLX_DEMO=1` after installing `cdp-connect-kit[mlx]` to enable the live Launcher calls.

Optional marker extra (installs nothing): `pip install human-input-kit[mlx]`

## CLI

| Command | Description |
|---------|-------------|
| `human-input demo-scroll --url URL` | Scroll + idle jitter demo |
| `human-input record --duration SEC -o FILE` | Record gestures JSON |
| `human-input replay FILE` | Replay saved gestures (schema-validated) |
| `human-input --seed N` | Global RNG seed on all subcommands (default `42`) |

## API

| Module | Use with |
|--------|----------|
| `human_input_kit` | Playwright **sync** `Page` |
| `human_input_kit.async_` | Playwright **async** `Page` |
| `human_input_kit.bezier` | Path math only (`bezier_mouse_path`) |

| Function | Description |
|----------|-------------|
| `bezier_mouse_path(start, end, steps=25)` | Cubic Bezier point list (sync, fast) |
| `move_mouse_along(page, path)` | Animate mouse along path |
| `human_type(page, selector, text)` | Variable per-char typing delays |
| `random_scroll(page, bursts=3)` | Random wheel bursts with pauses |
| `idle_jitter(page, moves=4)` | Small idle hand movements |
| `seed_rng(n)` | Deterministic variance for tests/demos |
| `load_recording(path, validate=True)` | Load gestures JSON with schema check |

### Gesture format

```json
{
  "version": 1,
  "url": "https://news.ycombinator.com",
  "events": [
    {"type": "move", "t": 0.0, "x": 120, "y": 80},
    {"type": "scroll", "t": 1.2, "dy": 320}
  ]
}
```

## Behavioral mimicry vs profile isolation

Human-like mouse paths and scroll timing can reduce **obvious automation cadence**, but behavioral mimicry alone is **necessary and insufficient** for production multi-account workflows.

Detection stacks also correlate:

- Browser fingerprint consistency (UA, WebGL, Client Hints)
- IP / proxy reputation
- Cookie and storage isolation
- TLS and network signals

Use `human-input-kit` for **warmup and interaction polish** inside an already-isolated profile (dedicated browser profile, proxy, and storage boundary). Pair with [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) and [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) for profile-level QA.

## When mechanical clicks still get flagged (playbook)

Behavior polish helps **cadence** — not fingerprint or IP. Typical order of operations:

| Signal still failing | Tool | Action |
|----------------------|------|--------|
| Teleport mouse / constant intervals | `human-input-kit` | Bezier paths, `--seed` for reproducible demos |
| UA / screen / timezone mismatch | [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | Audit profile before warmup |
| `navigator.webdriver` / headless leaks | [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | Compare vanilla vs Launcher CDP |
| One profile ok, N profiles not | `automation-farm-runner` | `farm-runner mlx-pool` + warmup script reading `CDP_URL` |

**Warmup pipeline (single profile):**

```bash
export MLX_TOKEN=... MLX_FOLDER_ID=...
# cdp-connect-kit starts profile → CDP_URL
CDP_URL=http://127.0.0.1:PORT python examples/mlx_warmup_demo.py --profile-id UUID
human-input --seed 42 demo-scroll --url https://news.ycombinator.com
cdp-probe mlx --profile-id UUID --url https://example.com
```


**Coupon hub:** [Multilogin promo codes](https://anti-detect.github.io/) — guides for `SAAS50` / `MIN50`, pricing comparisons, and workflow playbooks.
**Warmup at scale:** farm job imports `human_input_kit`, reads `CDP_URL` / `PROFILE_ID` from env — gestures stay in this package; queueing stays in `farm-runner`.

**Folder-scale partner note:** N-profile pools attach CDP via [cdp-connect-kit](https://pypi.org/project/cdp-connect-kit/), then warmup on `CDP_URL`. New to MLX? [Multilogin X](https://multilogin.com?a_aid=saas) · `SAAS50` (verify before checkout) · full coupons: `human-input --show-deal`.

## Limitations

- **Playwright only** — APIs expect a Playwright `Page`.
- **Record mode** captures DOM events + scripted warmup; not a full OS-level input recorder.
- **Not undetectable** — reduces mechanical patterns; does not spoof fingerprints or network identity.
- **Headless motion** — some sites behave differently in headless Chromium.

## Production

For **many profiles** (folder pool, cron, concurrency), use **`farm-runner`** (`automation-farm-runner`) with a warmup script that imports `human_input_kit` and reads `CDP_URL` / `PROFILE_ID`. This package is the gesture library; the farm runner owns MLX pool lifecycle.

**Partner note (affiliate):** Human-like input pays off **inside** isolated Multilogin X profiles (proxy + fingerprint already matched) — not on leaky vanilla Chromium. If folder-scale warmup is your bottleneck, eligible new browser purchases may accept code **`SAAS50`** at [multilogin.com](https://multilogin.com?a_aid=saas) — verify terms before checkout. Demos and recipes work without MLX. Full disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md). Deals hub: [anti-detect.github.io](https://anti-detect.github.io/). Coupon details only via `human-input --show-deal` (never printed by default).

**FAQ:** [docs/FAQ.md](docs/FAQ.md) — human-like mouse movement, Playwright scroll warmup, bot detection cadence.





## Related tools (on PyPI)

| Package | CLI | Role |
|---------|-----|------|
| [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | `cdp-probe` | CDP / WebDriver exposure score |
| [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) | `cookie-bridge` | Netscape ↔ Playwright cookies |
| [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/) | `proxy-lane` | Proxy TCP / HTTP / geo / DNSBL |
| [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | `fp-coherence` | UA / screen / timezone lint |

**Toolkit pipeline:** `proxy-lane check` → `fp-coherence audit` → automate → `cdp-probe run` → `cookie-bridge validate`

## License

MIT

---

**Production antidetect (partner):** [Multilogin X](https://multilogin.com?a_aid=saas) · Code `SAAS50` (-50% browser) · [MIN50](https://multilogin.com?a_aid=saas) (-50% cloud phone)  
Affiliate disclosure — we may earn a commission; offers change on the vendor site. More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Multilogin promo codes](https://anti-detect.github.io/)
