the-bumblebee 2.0.0

Human-like mouse and keyboard automation with an optional packaged RL mouse policy.

🐝 Bumblebee

Human-like mouse and keyboard automation for Python, with an optional packaged SAC mouse policy for RL-generated cursor paths.

Bumblebee v2 focuses on:

• a lightweight runtime API for mouse and keyboard automation
• configurable movement/typing profiles
• custom and RL mouse path providers
• a packaged default SAC mouse model
• local tooling for preparing data, training, and visualizing mouse policies

Detailed usage lives in docs/. This README is only the quick start.

---

Installation

Runtime only:

uv add the-bumblebee

Runtime plus packaged RL model loading:

uv add "the-bumblebee[rl]"

Local development:

git clone https://github.com/arpan404/bumblebee.git
cd bumblebee
uv sync --group dev

Local RL training tools:

uv sync --group train

---

Quick examples

Mouse

from bumblebee import Mouse, MouseBounds

mouse = Mouse(fail_safe=True)
mouse.set_profile("natural")
mouse.set_speed(1200)

mouse.move(500, 300)
mouse.click()
mouse.drag_to(700, 450)
mouse.scroll(-3)

# Click a random safe point inside a UI rectangle.
mouse.click_in_bounds(MouseBounds(100, 200, 260, 240), padding=6)

More: Mouse API

Keyboard

from bumblebee import Keyboard

keyboard = Keyboard()
keyboard.set_profile("careful")
keyboard.type("Hello from Bumblebee.", wpm=70, typo_rate=1)
keyboard.hotkey("cmd", "a")  # use "ctrl" on Windows/Linux

More: Keyboard API

Packaged RL mouse model

Install with the-bumblebee[rl], then:

from bumblebee import Mouse
from bumblebee.rl.policy import SB3MousePolicyPathProvider

provider = SB3MousePolicyPathProvider.from_packaged(deterministic=False)
mouse = Mouse(path_provider=provider)
mouse.move(700, 450)

More: Packaged model and release assets

---

Documentation

Topic	Link
Installation	docs/installation.md
Mouse API	docs/mouse.md
Keyboard API	docs/keyboard.md
Examples	docs/examples.md
RL workflow	docs/rl-workflow.md
Architecture	docs/architecture.md
Model/release assets	docs/models-and-releases.md
Publishing	PUBLISHING.md
Security	SECURITY.md

---

Model and dataset policy

The wheel includes the default model:

bumblebee/models/sac_mouse_v2.zip

The dataset is not included in the wheel. Large datasets/checkpoints/logs should be distributed through GitHub Releases or another artifact host.

---

Development checks

uv run black --check .
uv run isort --check-only .
uv run python -m compileall scripts src
uv build
uv run twine check dist/*

CI runs these checks and verifies that the packaged model is present in the wheel.

---

Safety

• Mouse(fail_safe=True) is the default.
• Move the cursor to a screen corner to trigger PyAutoGUI's fail-safe.
• Only automate systems and applications you are allowed to control.
• Be careful with real clicks, typing, and clipboard operations.

---

Contributing

See CONTRIBUTING.md.