multirandom 0.0.5
🎲 The truth external PyPI random package, have true_rand, virt_rand, hash_rand, ...
Requires Python: >=3.9

# MultiRandom 🎲

A comprehensive library for exploring and generating randomness across the spectrum—from true physical entropy to mathematical pseudo-randomness and everything in between.

## 🌟 Overview

**MultiRandom** is designed for developers, researchers, and hobbyists who want to understand high-quality randomness. It provides tools to fetch random data from quantum sources, physical human interaction, and modern mathematical algorithms.

> [!WARNING]
> **Security Note**: This library contains both "True" and "Pseudo" random sources. While some sources (like QRNG) are highly secure, others (like LCGs) are provided for educational purposes and include **reverse logic** to demonstrate their insecurity. Always use the appropriate generator for your use case.

---

## 🏗 Project Structure

```text
multirandom/
└── src/
    └── multirandom/
        ├── true_rand/          # Physical & Hardware Entropy
        │   ├── rand_via_clicks.py       # Human-in-the-loop entropy
        │   ├── rand_using_online_api.py # Quantum & Hardware APIs (ANU QRNG, Roll-API)
        │   └── weather_rand.py          # [Coming Soon] Weather-based entropy
        ├── virt_rand/          # Mathematical Randomness (PRNGs)
        │   ├── xor_shift.py             # XorShift & Xoshiro Family
        │   ├── rand_using_virt_lcg.py   # Linear Congruential Generators (LCGs)
        │   └── flash_rand_and_reverse.py # [Coming Soon] Specialized PRNGs
        └── hash_rand/          # Hash-based Generators
            ├── sha_rand.py              # SHA-1, SHA-256, SHA-512 based PRNGs
            └── original_random.py       # Wrapper for Python's built-in random
```

---

## 🛠 Features & Usage

### 1. Human-in-the-loop Entropy (`true_rand`)
Uses `pyautogui` and Windows API to capture sub-microsecond timing jitter and spatial coordinates from physical mouse clicks.

```python
from multirandom.true_rand.rand_via_clicks import RealRandomUsingBetweenMixedClicks

# Requires a sequence of Left -> Right -> Middle clicks to seed
gen = RealRandomUsingBetweenMixedClicks()
print(gen.random())
```

### 2. Physical & Hardware APIs (`true_rand`)
Fetch "True" randomness from remote physical processes.

- **Australian National University (ANU)**: Quantum vacuum noise via QRNG.
- **Random.org**: Atmospheric noise.
- **Roll-API**: Physical dice rolling hardware.
- **Weather Entropy**: (In development) Fetching randomness from real-time weather stations.

### 3. Bit-Shift Generators (`virt_rand`)
Implementations of the most popular mathematical generators used in modern systems.

- **Original XorShift**: Includes `reverse_roll()` to demonstrate mathematical reversibility.
- **Scrambled Variants**: Xorwow (CUDA), Xorshift+ (V8/Webkit).
- **Modern Xoshiro**: Xoshiro256**, Xoroshiro128++ (Minecraft Java 1.18+).

### 4. Mathematical LCGs (`virt_rand`)
Classic Linear Congruential Generators with customizable shift parameters. Includes `reverse_roll()` methods to demonstrate the insecurity of simple modular arithmetic.

---

## 🚀 Installation & Setup

### Requirements
- Python 3.9+
- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`)

### Installation
```bash
pip install -r requirements.txt
```

### Usage
```python
from multirandom.virt_rand.xor_shift import Xorshift32

# Create a 32-bit XorShift generator
gen = Xorshift32(seed=12345)
print(gen.roll())
```

---

## 📺 Educational Resources
This project focuses on the limits of computer-generated randomness. For more context, check out:
- [Why computers can't generate truly random numbers](https://youtu.be/XDsYPXRCXAs?si=oDaFsqZyNJWVXwEi)

---

## 📜 License
Provided for educational and research purposes under the GNU General Public License v3 (G GPLv3).