human-input-kit 0.2.1

Human-like Playwright mouse, scroll, and typing — Bezier warmup with deterministic seeds. CLI: human-input.

human-input-kit

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

pip install human-input-kit
human-input --help

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

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

pip install human-input-kit
playwright install chromium

Development:

pip install human-input-kit[dev]

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

Quick start

# 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):

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_):

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/ 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:

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

{
  "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 and 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	Audit profile before warmup
navigator.webdriver / headless leaks	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):

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

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.

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 — verify terms before checkout. Demos and recipes work without MLX. Full disclosure: docs/AFFILIATE.md. Coupon details only via human-input --show-deal (never printed by default).

FAQ: docs/FAQ.md — human-like mouse movement, Playwright scroll warmup, bot detection cadence.

Related tools (on PyPI)

Package	CLI	Role
playwright-cdp-probe	cdp-probe	CDP / WebDriver exposure score
cookie-jar-bridge	cookie-bridge	Netscape ↔ Playwright cookies
proxy-lane-checker	proxy-lane	Proxy TCP / HTTP / geo / DNSBL
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: Multilogin X · Code SAAS50 (-50% browser) · MIN50 (-50% cloud phone)
More scripts: @Multilogin_Scripts_Bot · Coupons