Metadata-Version: 2.1
Name: humanio
Version: 0.1.0
Summary: Behaviorally realistic human mouse and keyboard I/O simulation and bot detection.
Requires-Python: >=3.9
License: LicenseRef-Proprietary
Author: Jayden C
Author-email: developer.jaydenc@outlook.com.au
Keywords: human-like,mouse-movement,keystroke-dynamics,typing-simulation,bot-detection,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Software Development :: Testing
Project-URL: Homepage, https://github.com/CogForgeLabs/HumanIO
Project-URL: Repository, https://github.com/CogForgeLabs/HumanIO
Project-URL: Documentation, https://github.com/CogForgeLabs/HumanIO/tree/main/docs
Project-URL: Issues, https://github.com/CogForgeLabs/HumanIO/issues
Requires-Dist: numpy>=1.24
Requires-Dist: cryptography>=42
Requires-Dist: keyring>=24
Provides-Extra: mouse-control
Requires-Dist: pyautogui>=0.9; extra == "mouse-control"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == "viz"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.29; extra == "server"
Provides-Extra: build
Requires-Dist: nuitka>=2.4; extra == "build"
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == "build"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: numpy>=1.24; extra == "dev"
Requires-Dist: matplotlib>=3.6; extra == "dev"
Requires-Dist: fastapi>=0.110; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Description-Content-Type: text/markdown

# 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](#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.

[![humanio demo](docs/media/humanio-demo.png)](docs/media/humanio-demo.mp4)

▶ **[Watch the video](docs/media/humanio-demo.mp4)** — regenerate it with
`pip install "humanio[viz]"` then `python examples/visualize.py`.

---

## Installation

```bash
pip install humanio
```

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

```bash
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:

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

---

## Mouse

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

```python
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`:

```python
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):

```python
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 `KeystrokeEvent`s with realistic inter-key
timing, errors and corrections. It never sleeps — schedule the events yourself
using `event.press_time_ms`.

```python
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`](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            |

```python
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`](docs/architecture/licensing.md).

### Try the whole flow locally (no Stripe/Cryptlex)

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

Or against the real reference server with signed responses:

```bash
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/`](docs/research):

- [Human Mouse Movement](docs/research/human-mouse-movement.md)
- [Human Typing](docs/research/human-typing.md)
- [Bot Detection & Evasion](docs/research/bot-detection-and-evasion.md)

## Development

```bash
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](EULA.md); see [LICENSE](LICENSE). No source code is licensed or provided.
