humanio 0.1.0

Behaviorally realistic human mouse and keyboard I/O simulation and bot detection.

humanio

Behaviorally realistic human I/O simulation and bot detection — for both mouse and keyboard.

humanio generates human-like input data (mouse trajectories and keystroke event streams) grounded in motor-control and keystroke-dynamics research, and ships matching detectors that score input as human or bot.

The generators never touch the OS by default — they produce timed event data that you feed into whatever automation backend you use (PyAutoGUI, Playwright, Selenium, …). Actually moving the cursor is opt-in via MouseExecutor.

humanio is proprietary, subscription software distributed as compiled binaries. Generation and detection calls are metered. A metered free tier is available (anonymous or signed-in); a subscription removes the cap. See Licensing below. Source code is not provided.

humanio
├── mouse    HumanMouse · MovementDetector · MouseExecutor
└── typing   SimulationEngine · BotClassifier · TypistProfile · KeystrokeEvent

Demo

Human-like input (teal/green) vs a naive bot (red) — side by side, scored live by the matching detector. The human mouse path curves and corrects through submovements; the bot moves in straight constant-velocity lines. The human typing stream varies its timing and fixes a typo; the bot types at a perfectly uniform cadence.

▶ Watch the video — regenerate it with pip install "humanio[viz]" then python examples/visualize.py.

---

Installation

pip install humanio

To enable real cursor replay (MouseExecutor), install the optional extra:

pip install "humanio[mouse-control]"   # adds pyautogui

On first use the library establishes a metered free-tier session. To unlock unlimited use, activate a subscription:

import humanio
humanio.activate("YOUR-LICENSE-KEY")

---

Mouse

Generate a human-like trajectory and check it against the detector:

from humanio.mouse import HumanMouse, MovementDetector

mouse = HumanMouse(seed=42)
trajectory = mouse.generate(start=(100, 200), end=(800, 450), target_width=20)
# trajectory is a list[Point] with (x, y, t) — t in seconds from movement start.

detector = MovementDetector()
result = detector.classify(trajectory)
print(result.label, f"{result.confidence:.0%}")   # e.g. "human 87%"
print(result.explanations)                         # which rules, if any, flagged it

Every trajectory models Fitts's Law timing, an asymmetric bell-shaped velocity profile, 2–5 overlapping minimum-jerk submovements, signal-dependent neuromotor noise, undershoot-and-correct behavior, lateral path curvature, and homing-phase micro-jitter. Per-user variation comes from a UserProfile:

from humanio._shared.types import UserProfile

profile = HumanMouse.random_profile(seed=7)   # plausible randomized individual
mouse = HumanMouse(profile=profile, seed=7)

Replaying through the real cursor (requires the mouse-control extra):

from humanio.mouse import MouseExecutor

executor = MouseExecutor(speed_multiplier=1.0)
executor.execute_with_click(trajectory, button="left")

---

Typing

The simulator produces a list of KeystrokeEvents with realistic inter-key timing, errors and corrections. It never sleeps — schedule the events yourself using event.press_time_ms.

from humanio.typing import SimulationEngine, BotClassifier, TypistProfile

profile = TypistProfile.average()      # or .expert() / .novice() / TypistProfile(base_wpm=55, error_rate=0.04)
engine = SimulationEngine(profile)

events = engine.type_text("Hello, world! This is a typing simulation.")
for ev in events[:5]:
    print(f"{ev.key!r:8}  press={ev.press_time_ms:7.1f}ms  dwell={ev.dwell_ms:5.1f}ms")

classifier = BotClassifier()
result = classifier.classify(events)
print(result.verdict, f"bot_probability={result.bot_probability:.2f}")
print(result.feature_scores)   # per-feature breakdown

See examples/typing_example.py for a fuller walkthrough, including scheduling events against pyautogui and contrasting a human-like stream with a perfectly-uniform bot stream.

---

Licensing

humanio is metered. Each generation/detection call costs one or more actions against your current tier:

Tier	How to get it	Allowance
Anonymous	nothing — just run it	small monthly quota
Free account	humanio.login("account-id")	larger monthly quota
Subscriber	humanio.activate("LICENSE-KEY")	unlimited

import humanio

humanio.activate("YOUR-LICENSE-KEY")   # unlock a subscription
print(humanio.status())                # tier, usage, quota, reset time

try:
    traj = HumanMouse(seed=1).generate((0, 0), (800, 400))
except humanio.QuotaExceeded as e:
    print("Free-tier limit reached — subscribe at", e.url)
except humanio.SubscriptionRequired as e:
    print("Renew at", e.url)

Usage is metered server-side, so quotas can't be reset by clearing local state. Subscription status is cached with a short offline grace window and re-validated periodically. How this is enforced (compiled binaries, a device-bound tamper-evident ledger, server-anchored usage, per-release secret rotation, Ed25519-signed responses) is summarized in docs/architecture/licensing.md.

Try the whole flow locally (no Stripe/Cryptlex)

python examples/licensing_demo.py     # anonymous → free → subscriber, in-process

Or against the real reference server with signed responses:

pip install ".[server]"
uvicorn server.app:app --port 8000           # prints its signing public key
# in another shell:
HUMANIO_BACKEND_URL=http://127.0.0.1:8000 \
HUMANIO_SERVER_PUBKEY_HEX=<printed key> \
HUMANIO_DEV_TIER=anonymous \
python -c "import humanio; from humanio.mouse import HumanMouse; \
HumanMouse(seed=1).generate((0,0),(300,200)); print(humanio.status())"

Useful env vars for local/dev runs: HUMANIO_DEV_TIER (anonymous/free/ subscriber), HUMANIO_BACKEND_URL, HUMANIO_SERVER_PUBKEY_HEX, HUMANIO_LICENSE_KEY, HUMANIO_LEDGER_DIR.

---

Project layout

humanio/
├── src/humanio/
│   ├── mouse/         trajectory generation, detection, cursor replay
│   ├── typing/        keystroke simulation (simulation/) and detection (detection/)
│   ├── _license/      sign-in, subscription gating, metered free tier
│   └── _shared/       shared types (Point, Trajectory, UserProfile, …) and RNG
├── server/           reference licensing + metering server (FastAPI)
├── packaging/        per-build secret rotation + Nuitka compile
├── tests/
├── examples/
├── docs/
│   ├── research/      the research reports the models are built on
│   └── architecture/  licensing & hardening design
├── pyproject.toml
├── EULA.md
└── LICENSE

Documentation

The behavioral models are derived from the research compiled in docs/research/:

• Human Mouse Movement
• Human Typing
• Bot Detection & Evasion

Development

pip install -e ".[dev]"
pytest

Responsible use

humanio is intended for legitimate purposes: testing the robustness of your own bot-detection systems, building accessibility and human-factors tooling, research, and QA automation. Do not use it to evade detection on systems you do not own or operate, or to violate any site's terms of service.

License

Proprietary © 2026 Jayden C. All rights reserved. Use is governed by the EULA; see LICENSE. No source code is licensed or provided.