human-input-kit 0.2.1__py3-none-any.whl

examples/demo_warmup.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Example warmup script using human-input-kit with Playwright (async API).
+
+Run from the package root::
+
+    python examples/demo_warmup.py
+    python examples/demo_warmup.py --seed 42 --url https://news.ycombinator.com
+
+Or after install::
+
+    python -m examples.demo_warmup  # if on PYTHONPATH
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from human_input_kit import seed_rng
+from human_input_kit.async_ import bezier_mouse_path, idle_jitter, move_mouse_along, random_scroll
+from playwright.async_api import async_playwright
+
+
+async def warmup(*, url: str, seed: int, headless: bool) -> None:
+    seed_rng(seed)
+    async with async_playwright() as playwright:
+        browser = await playwright.chromium.launch(headless=headless)
+        page = await browser.new_page(viewport={"width": 1280, "height": 720})
+        await page.goto(url, wait_until="domcontentloaded")
+
+        path = bezier_mouse_path((80, 120), (640, 360), steps=20)
+        await move_mouse_along(page, path)
+        await random_scroll(page, bursts=4)
+        await idle_jitter(page, moves=3)
+
+        title = await page.title()
+        print(f"Warmup complete (seed={seed}): {title}")
+        await browser.close()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Human-input-kit warmup demo")
+    parser.add_argument("--url", default="https://news.ycombinator.com")
+    parser.add_argument("--seed", type=int, default=42, help="RNG seed for reproducible motion")
+    parser.add_argument("--headed", action="store_true", help="Run browser with UI")
+    args = parser.parse_args()
+    asyncio.run(warmup(url=args.url, seed=args.seed, headless=not args.headed))
+
+
+if __name__ == "__main__":
+    main()

examples/mlx_warmup_demo.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""MLX profile warmup demo — pseudocode + optional cdp-connect-kit peer integration.
+
+This script is **documentation-first**: it shows how to run human-input-kit warmup
+gestures against a Multilogin X profile started via the local Launcher API.
+
+Peer dependencies (install separately — NOT required by human-input-kit):
+
+    pip install human-input-kit
+    pip install cdp-connect-kit[mlx]   # Launcher start/stop + CDP helpers
+    playwright install chromium
+
+Environment:
+
+    export MLX_TOKEN=your_bearer_token
+    export MLX_FOLDER_ID=your-folder-uuid
+
+Run with an existing CDP endpoint (skip Launcher TODOs):
+
+    CDP_URL=http://127.0.0.1:55513 python examples/mlx_warmup_demo.py --profile-id UUID
+
+Or after wiring Launcher start below:
+
+    python examples/mlx_warmup_demo.py --profile-id UUID --url https://example.com
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+from typing import TYPE_CHECKING
+
+from human_input_kit import seed_rng
+from human_input_kit.async_ import bezier_mouse_path, idle_jitter, move_mouse_along, random_scroll
+from playwright.async_api import async_playwright
+
+if TYPE_CHECKING:
+    from cdp_connect_kit.mlx import MlxLauncher, MlxSession
+
+
+def _require_cdp_connect_kit() -> tuple[type[MlxLauncher], type[MlxSession]]:
+    try:
+        from cdp_connect_kit.mlx import MlxLauncher, MlxSession
+    except ImportError as exc:
+        msg = (
+            "cdp-connect-kit[mlx] is a peer dependency for Launcher integration.\n"
+            "Install with: pip install cdp-connect-kit[mlx]\n"
+            "Or set CDP_URL to an already-running profile and skip Launcher start."
+        )
+        raise SystemExit(msg) from exc
+    return MlxLauncher, MlxSession
+
+
+async def start_mlx_profile(
+    *,
+    profile_id: str,
+    folder_id: str | None,
+    token: str | None,
+    headless: bool,
+) -> str:
+    """Return CDP HTTP endpoint for the started MLX profile.
+
+    TODO: Uncomment and use cdp-connect-kit once peer deps are installed.
+    """
+    cdp_url = os.environ.get("CDP_URL")
+    if cdp_url:
+        print(f"Using CDP_URL from environment: {cdp_url}")
+        return cdp_url.rstrip("/")
+
+    # --- Launcher start (cdp-connect-kit pattern) ---
+    # TODO: Remove the guard below and call MlxLauncher when ready for production.
+    if os.environ.get("HUMAN_INPUT_KIT_MLX_DEMO") != "1":
+        print(
+            "Pseudocode mode: Launcher start is stubbed.\n"
+            "  1. pip install cdp-connect-kit[mlx]\n"
+            "  2. export MLX_TOKEN=... MLX_FOLDER_ID=...\n"
+            "  3. export HUMAN_INPUT_KIT_MLX_DEMO=1\n"
+            "  4. Re-run this script\n"
+            "Or export CDP_URL=http://127.0.0.1:PORT from an already-started profile."
+        )
+        raise SystemExit(2)
+
+    resolved_folder = folder_id or os.environ.get("MLX_FOLDER_ID")
+    resolved_token = token or os.environ.get("MLX_TOKEN")
+    if not resolved_folder or not resolved_token:
+        raise SystemExit(
+            "Set MLX_FOLDER_ID + MLX_TOKEN (or pass --folder-id / --token), "
+            "or export CDP_URL to skip Launcher start."
+        )
+
+    MlxLauncher, _MlxSession = _require_cdp_connect_kit()
+    launcher = MlxLauncher(token=resolved_token)
+    try:
+        session = launcher.start_profile(
+            resolved_folder,
+            profile_id,
+            automation_type="playwright",
+            headless=headless,
+        )
+        print(f"MLX Launcher started profile {profile_id} → {session.http_endpoint}")
+        return session.http_endpoint
+    finally:
+        launcher.close()
+
+
+async def stop_mlx_profile(*, profile_id: str, token: str | None) -> None:
+    """Stop MLX profile via Launcher API."""
+    if os.environ.get("CDP_URL"):
+        print("CDP_URL was supplied externally — skipping Launcher stop.")
+        return
+
+    # TODO: Call launcher.stop_profile(profile_id) when HUMAN_INPUT_KIT_MLX_DEMO=1.
+    if os.environ.get("HUMAN_INPUT_KIT_MLX_DEMO") != "1":
+        return
+
+    MlxLauncher, _ = _require_cdp_connect_kit()
+    resolved_token = token or os.environ.get("MLX_TOKEN")
+    if not resolved_token:
+        return
+    launcher = MlxLauncher(token=resolved_token)
+    try:
+        launcher.stop_profile(profile_id)
+        print(f"Stopped MLX profile {profile_id}")
+    finally:
+        launcher.close()
+
+
+async def warmup_over_cdp(
+    *,
+    cdp_endpoint: str,
+    url: str,
+    seed: int,
+) -> None:
+    """Connect Playwright over CDP and run human-input-kit warmup gestures."""
+    seed_rng(seed)
+    async with async_playwright() as playwright:
+        browser = await playwright.chromium.connect_over_cdp(cdp_endpoint)
+        context = browser.contexts[0] if browser.contexts else await browser.new_context()
+        page = context.pages[0] if context.pages else await context.new_page()
+        await page.goto(url, wait_until="domcontentloaded")
+
+        path = bezier_mouse_path((80, 120), (640, 360), steps=20)
+        await move_mouse_along(page, path)
+        await random_scroll(page, bursts=4)
+        await idle_jitter(page, moves=3)
+
+        title = await page.title()
+        print(f"MLX warmup complete (seed={seed}): {title}")
+        await browser.close()
+
+
+async def mlx_warmup_flow(
+    *,
+    profile_id: str,
+    folder_id: str | None,
+    token: str | None,
+    url: str,
+    seed: int,
+    headless: bool,
+) -> None:
+    """End-to-end: Launcher start → CDP connect → warmup → Launcher stop."""
+    cdp_endpoint = await start_mlx_profile(
+        profile_id=profile_id,
+        folder_id=folder_id,
+        token=token,
+        headless=headless,
+    )
+    try:
+        await warmup_over_cdp(cdp_endpoint=cdp_endpoint, url=url, seed=seed)
+    finally:
+        await stop_mlx_profile(profile_id=profile_id, token=token)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="MLX profile warmup demo (peer: cdp-connect-kit[mlx])",
+    )
+    parser.add_argument("--profile-id", required=True, help="MLX profile UUID")
+    parser.add_argument("--folder-id", default=None, help="MLX folder UUID (or MLX_FOLDER_ID)")
+    parser.add_argument("--token", default=None, help="Bearer token (or MLX_TOKEN)")
+    parser.add_argument("--url", default="https://news.ycombinator.com")
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--headed", action="store_true", help="Launcher headless_mode=false")
+    args = parser.parse_args()
+
+    asyncio.run(
+        mlx_warmup_flow(
+            profile_id=args.profile_id,
+            folder_id=args.folder_id,
+            token=args.token,
+            url=args.url,
+            seed=args.seed,
+            headless=not args.headed,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

human_input_kit/__init__.py

@@ -0,0 +1,23 @@
+"""Human-like input helpers for Playwright (sync API by default)."""
+
+from human_input_kit import async_ as async_
+from human_input_kit.bezier import Point, bezier_mouse_path
+from human_input_kit.rng import get_rng, seed_rng
+from human_input_kit.sync_ import human_type, idle_jitter, move_mouse_along, random_scroll
+from human_input_kit.sync_ import replay_file as replay_file
+from human_input_kit.sync_ import replay_gestures as replay_gestures
+
+__all__ = [
+    "Point",
+    "async_",
+    "bezier_mouse_path",
+    "get_rng",
+    "human_type",
+    "idle_jitter",
+    "move_mouse_along",
+    "random_scroll",
+    "replay_file",
+    "replay_gestures",
+    "seed_rng",
+]
+__version__ = "0.2.1"

human_input_kit/async_.py

@@ -0,0 +1,19 @@
+"""Playwright async API — human-like input helpers."""
+
+from __future__ import annotations
+
+from human_input_kit.bezier import bezier_mouse_path, move_mouse_along
+from human_input_kit.idle import idle_jitter
+from human_input_kit.keyboard import human_type
+from human_input_kit.replay import replay_file, replay_gestures
+from human_input_kit.scroll import random_scroll
+
+__all__ = [
+    "bezier_mouse_path",
+    "human_type",
+    "idle_jitter",
+    "move_mouse_along",
+    "random_scroll",
+    "replay_file",
+    "replay_gestures",
+]

human_input_kit/bezier.py

@@ -0,0 +1,68 @@
+"""Bezier mouse path generation."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+from human_input_kit.rng import get_rng
+
+Point = tuple[float, float]
+
+
+def _cubic_bezier(t: float, p0: Point, p1: Point, p2: Point, p3: Point) -> Point:
+    u = 1.0 - t
+    x = u**3 * p0[0] + 3 * u**2 * t * p1[0] + 3 * u * t**2 * p2[0] + t**3 * p3[0]
+    y = u**3 * p0[1] + 3 * u**2 * t * p1[1] + 3 * u * t**2 * p2[1] + t**3 * p3[1]
+    return x, y
+
+
+def bezier_mouse_path(
+    start: Point,
+    end: Point,
+    *,
+    steps: int = 25,
+    spread: float = 0.35,
+) -> list[Point]:
+    """Return a human-like curved mouse path between two points."""
+    rng = get_rng()
+    if steps < 2:
+        return [start, end]
+
+    dx = end[0] - start[0]
+    dy = end[1] - start[1]
+    distance = math.hypot(dx, dy) or 1.0
+
+    offset = distance * spread
+    cp1 = (
+        start[0] + dx * 0.25 + rng.uniform(-offset, offset),
+        start[1] + dy * 0.25 + rng.uniform(-offset, offset),
+    )
+    cp2 = (
+        start[0] + dx * 0.75 + rng.uniform(-offset, offset),
+        start[1] + dy * 0.75 + rng.uniform(-offset, offset),
+    )
+
+    points: list[Point] = []
+    jitter = min(3.0, distance * 0.01)
+    for i in range(steps):
+        t = i / (steps - 1)
+        x, y = _cubic_bezier(t, start, cp1, cp2, end)
+        if i in {0, steps - 1}:
+            points.append((x, y))
+        else:
+            points.append((x + rng.uniform(-jitter, jitter), y + rng.uniform(-jitter, jitter)))
+    points[0] = start
+    points[-1] = end
+    return points
+
+
+async def move_mouse_along(page: object, path: Sequence[Point], *, delay_ms: float = 8.0) -> None:
+    """Move Playwright mouse along a bezier path."""
+    import asyncio
+
+    mouse = page.mouse  # type: ignore[attr-defined]
+    for x, y in path:
+        await mouse.move(x, y)
+        if delay_ms > 0:
+            await asyncio.sleep(delay_ms / 1000.0)

human_input_kit/cli.py

@@ -0,0 +1,100 @@
+"""Click CLI for human-input."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import click
+from playwright.async_api import async_playwright
+
+from human_input_kit.gestures import load_recording, save_recording
+from human_input_kit.idle import idle_jitter
+from human_input_kit.record import record_gestures
+from human_input_kit.replay import replay_file
+from human_input_kit.rng import seed_rng
+from human_input_kit.scroll import random_scroll
+
+
+@click.group(invoke_without_command=True)
+@click.option("--show-deal", is_flag=True, help="Print Multilogin coupon info and exit.")
+@click.option("--seed", default=42, show_default=True, help="RNG seed for reproducible motion.")
+@click.version_option(package_name="human-input-kit")
+@click.pass_context
+def main(ctx: click.Context, show_deal: bool, seed: int) -> None:
+    """Human-like Playwright input helpers."""
+    if show_deal:
+        from human_input_kit.deal import print_show_deal
+
+        print_show_deal()
+        ctx.exit(0)
+    seed_rng(seed)
+    ctx.ensure_object(dict)
+    ctx.obj["seed"] = seed
+
+
+@main.command("demo-scroll")
+@click.option("--url", default="https://news.ycombinator.com", show_default=True)
+@click.option("--headless/--no-headless", default=True, show_default=True)
+@click.option("--bursts", default=5, show_default=True)
+def demo_scroll_cmd(url: str, headless: bool, bursts: int) -> None:
+    """Open a page and perform human-like scrolling + idle jitter."""
+
+    async def _run() -> None:
+        async with async_playwright() as playwright:
+            browser = await playwright.chromium.launch(headless=headless)
+            page = await browser.new_page(viewport={"width": 1280, "height": 720})
+            await page.goto(url, wait_until="domcontentloaded")
+            await random_scroll(page, bursts=bursts)
+            await idle_jitter(page, moves=5)
+            await browser.close()
+
+    asyncio.run(_run())
+    click.echo(f"Completed demo scroll on {url}")
+
+
+@main.command("record")
+@click.option("--url", default="https://news.ycombinator.com", show_default=True)
+@click.option("--duration", default=30.0, show_default=True, help="Seconds to record.")
+@click.option("-o", "--output", "output_path", type=click.Path(path_type=Path), required=True)
+@click.option("--headless/--no-headless", default=True, show_default=True)
+def record_cmd(url: str, duration: float, output_path: Path, headless: bool) -> None:
+    """Record gestures to JSON (includes scripted warmup actions)."""
+
+    async def _run() -> None:
+        async with async_playwright() as playwright:
+            browser = await playwright.chromium.launch(headless=headless)
+            page = await browser.new_page(viewport={"width": 1280, "height": 720})
+            await page.goto(url, wait_until="domcontentloaded")
+            recording = await record_gestures(page, duration=duration)
+            save_recording(output_path, recording)
+            await browser.close()
+
+    asyncio.run(_run())
+    click.echo(f"Saved {duration:.0f}s recording -> {output_path}")
+
+
+@main.command("replay")
+@click.argument("gestures_path", type=click.Path(exists=True, path_type=Path))
+@click.option("--headless/--no-headless", default=True, show_default=True)
+@click.option("--speed", default=1.0, show_default=True, help="Playback speed multiplier.")
+def replay_cmd(gestures_path: Path, headless: bool, speed: float) -> None:
+    """Replay a gestures JSON file."""
+    try:
+        load_recording(gestures_path, validate=True)
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    async def _run() -> None:
+        async with async_playwright() as playwright:
+            browser = await playwright.chromium.launch(headless=headless)
+            page = await browser.new_page(viewport={"width": 1280, "height": 720})
+            await replay_file(page, gestures_path, speed=speed)
+            await browser.close()
+
+    asyncio.run(_run())
+    click.echo(f"Replayed {gestures_path}")
+
+
+if __name__ == "__main__":
+    main()

human_input_kit/deal.py

@@ -0,0 +1,25 @@
+"""Multilogin partner coupon output for --show-deal."""
+
+from __future__ import annotations
+
+import click
+
+SHOW_DEAL_TEXT = """Partner info (affiliate links — optional, not required for human-input)
+
+Human-like scroll and mouse paths help cadence — not fingerprint or IP.
+They matter most inside isolated Launcher profiles at folder scale.
+
+Multilogin X — antidetect browser & cloud phone (verify eligibility before checkout)
+
+  SAAS50  — browser plans (eligible new purchases)
+  MIN50   — cloud phone (eligible new purchases)
+
+  https://multilogin.com/?ref=SAAS50
+  Coupons: https://anti-detect.github.io/
+  Scripts: https://t.me/Multilogin_Scripts_Bot
+
+Disclosure: we may earn a commission. Offers change; confirm on vendor site."""
+
+
+def print_show_deal() -> None:
+    click.echo(SHOW_DEAL_TEXT)

human_input_kit/gesture_schema.py

@@ -0,0 +1,90 @@
+"""Gesture recording JSON schema validation (no external jsonschema dependency)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+ALLOWED_EVENT_TYPES = frozenset({"move", "scroll", "type", "wait"})
+
+
+def validate_gesture_payload(payload: Any) -> list[str]:
+    """Return a list of validation error messages (empty if valid)."""
+    errors: list[str] = []
+
+    if not isinstance(payload, dict):
+        return ["Gesture file must be a JSON object"]
+
+    version = payload.get("version")
+    if version is None:
+        errors.append("Missing required field 'version'")
+    elif not isinstance(version, int) or version < 1:
+        errors.append("'version' must be a positive integer")
+
+    url = payload.get("url", "about:blank")
+    if not isinstance(url, str):
+        errors.append("'url' must be a string")
+
+    events = payload.get("events")
+    if events is None:
+        errors.append("Missing required field 'events'")
+        return errors
+    if not isinstance(events, list):
+        errors.append("'events' must be an array")
+        return errors
+
+    for index, item in enumerate(events):
+        prefix = f"events[{index}]"
+        if not isinstance(item, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+
+        event_type = item.get("type")
+        if event_type not in ALLOWED_EVENT_TYPES:
+            errors.append(f"{prefix}.type must be one of {sorted(ALLOWED_EVENT_TYPES)}")
+            continue
+
+        t = item.get("t")
+        if t is None:
+            errors.append(f"{prefix} missing required field 't'")
+        elif not isinstance(t, (int, float)) or t < 0:
+            errors.append(f"{prefix}.t must be a non-negative number")
+
+        errors.extend(_validate_event_fields(prefix, event_type, item))
+
+    return errors
+
+
+def _validate_event_fields(prefix: str, event_type: str, item: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+
+    if event_type == "move":
+        for field in ("x", "y"):
+            value = item.get(field)
+            if value is None:
+                errors.append(f"{prefix} move events require '{field}'")
+            elif not isinstance(value, (int, float)):
+                errors.append(f"{prefix}.{field} must be a number")
+    elif event_type == "scroll":
+        if item.get("dx") is None and item.get("dy") is None:
+            errors.append(f"{prefix} scroll events require 'dx' and/or 'dy'")
+        for field in ("dx", "dy"):
+            value = item.get(field)
+            if value is not None and not isinstance(value, (int, float)):
+                errors.append(f"{prefix}.{field} must be a number")
+    elif event_type == "type":
+        text = item.get("text")
+        if text is None:
+            errors.append(f"{prefix} type events require 'text'")
+        elif not isinstance(text, str):
+            errors.append(f"{prefix}.text must be a string")
+        selector = item.get("selector")
+        if selector is not None and not isinstance(selector, str):
+            errors.append(f"{prefix}.selector must be a string")
+    elif event_type == "wait":
+        duration = item.get("duration_ms")
+        if duration is None:
+            errors.append(f"{prefix} wait events require 'duration_ms'")
+        elif not isinstance(duration, (int, float)) or duration <= 0:
+            errors.append(f"{prefix}.duration_ms must be a positive number")
+
+    return errors

human_input_kit/gestures.py

@@ -0,0 +1,84 @@
+"""Gesture recording format."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+GestureType = Literal["move", "scroll", "type", "wait"]
+
+
+@dataclass(slots=True)
+class GestureEvent:
+    type: GestureType
+    t: float
+    x: float | None = None
+    y: float | None = None
+    dx: float | None = None
+    dy: float | None = None
+    text: str | None = None
+    selector: str | None = None
+    duration_ms: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+
+@dataclass(slots=True)
+class GestureRecording:
+    version: int = 1
+    url: str = "about:blank"
+    events: list[GestureEvent] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "version": self.version,
+            "url": self.url,
+            "events": [event.to_dict() for event in self.events],
+        }
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> GestureRecording:
+        events = []
+        for item in payload.get("events", []):
+            if isinstance(item, dict):
+                events.append(
+                    GestureEvent(
+                        type=item["type"],
+                        t=float(item.get("t", 0)),
+                        x=item.get("x"),
+                        y=item.get("y"),
+                        dx=item.get("dx"),
+                        dy=item.get("dy"),
+                        text=item.get("text"),
+                        selector=item.get("selector"),
+                        duration_ms=item.get("duration_ms"),
+                    )
+                )
+        return cls(
+            version=int(payload.get("version", 1)),
+            url=str(payload.get("url", "about:blank")),
+            events=events,
+        )
+
+
+def save_recording(path: Path | str, recording: GestureRecording) -> None:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(recording.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+
+def load_recording(path: Path | str, *, validate: bool = True) -> GestureRecording:
+    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    if validate:
+        from human_input_kit.gesture_schema import validate_gesture_payload
+
+        errors = validate_gesture_payload(payload)
+        if errors:
+            msg = "Invalid gesture file:\n" + "\n".join(f"  - {err}" for err in errors)
+            raise ValueError(msg)
+    if not isinstance(payload, dict):
+        raise ValueError("Gesture file must be a JSON object")
+    return GestureRecording.from_dict(payload)