ai_mouse

Human-like mouse trajectory and scroll wheel event generator. Inference runs on ONNX Runtime; the only runtime dependencies are numpy and onnxruntime.

Install

pip install git+https://github.com/<owner>/ai_mouse.git

For GPU inference (optional), replace onnxruntime with the GPU variant:

pip install onnxruntime-gpu      # CUDA / TensorRT
# or
pip install onnxruntime-directml # Windows DirectML

Quick start

Mouse trajectory

from ai_mouse import generate

points = generate(start=(100, 200), end=(900, 400))
# [(x, y, t_ms), ..., (cx, cy, t_down), (cx, cy, t_up)]

Scroll wheel

from ai_mouse import generate_scroll

events = generate_scroll(start_scroll_y=0, target_scroll_y=2000)
# [{"deltaY": 120, "deltaMode": 0, "t": 32}, ...]

Class API (recommended for repeated calls)

from ai_mouse import MouseModel

m = MouseModel()              # session created once
for target in target_list:
    pts = m.generate((cx, cy), target)

Custom providers / GPU

from ai_mouse import MouseModel

m = MouseModel(providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
# or
m = MouseModel(providers=["DmlExecutionProvider"])

Reproducibility

m.generate(start, end, seed=42)

API summary

Name	Purpose
generate(start, end, *, n_points=64, speed=None, click=True, seed=None)	One-shot call; internal lru_cache singleton
MouseModel(model_path=None, providers=None, seed=None)	Persistent session
generate_scroll(...) / ScrollModel(...)	Same shape for scroll
ai_mouse.errors.{ModelLoadError, GenerationError}	Exception hierarchy

Thread safety

MouseModel.generate and ScrollModel.generate are safe to call concurrently from multiple threads — ORT InferenceSession is itself thread-safe.

Development

The repo contains optional dev-only tooling under tools/ for training your own models, running the FastAPI web UI, and evaluating output quality. Install with the dev group:

uv sync --group dev

Common commands:

# Web UI (collect + train + verify in browser)
uv run python tools/serve.py

# Training (after collecting your own data)
uv run python -m tools train --data data/traces.jsonl --output data/models_v2

# Convert Balabit corpus to trace format
uv run python -m tools balabit-adapter --input data/balabit_raw \
    --output data/pretrain_traces.jsonl

# Eval report
uv run python -m tools eval --model-dir data/models_v2 \
    --reference data/pretrain_traces.jsonl --output data/eval_reports/report.md

# Re-export ONNX after retraining
uv run python -m tools.export_onnx --flow-ckpt data/models_v2 \
    --scroll-ckpt data/scroll_models --output src/ai_mouse/assets/

Tests:

uv run pytest tests/unit    # library-only (no torch)
uv run pytest tests/tools   # full dev suite

After retraining you need to re-export and rebuild the wheel for the new weights to ship; the in-app Verify endpoint always uses bundled weights.