Metadata-Version: 2.4
Name: randomrad
Version: 1.0.0
Summary: Minimal hardware-backed randomness library for Python with ESP32 serial input and automatic file fallback.
Author: Alwin Bestvater
License-Expression: MIT
Keywords: random,entropy,esp32,serial,hardware
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Dynamic: license-file

# randomrad - minimal package edition

`randomrad` is a small Python library that exposes a familiar `random`-like
API while sourcing bytes from external entropy instead of a deterministic
pseudo-random generator.

This folder contains the minimal package-style edition of the project. It is
suitable for installation as a local package and for demonstrating the core
API without the full GUI and report environment.

## Features

- `import randomrad as rr`
- random-like functions such as `randbytes`, `random`, `randint`, `choice`,
  `choices`, `shuffle` and `sample`
- ESP32 hardware backend over serial
- automatic fallback to a file backend
- host-side hardware buffer for faster repeated small requests
- package-specific `NotEnoughEntropy` exception
- no seed or replay mode by design

## Installation

Open PowerShell inside this folder:

```powershell
cd randomrad_pypi
python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e .
```

## Quick start

```python
import randomrad as rr

print(rr.randbytes(32))
print(rr.random())
print(rr.randint(1, 10))
print(rr.choice(["a", "b", "c"]))
print(rr.last_effective_backend())
print(rr.last_backend_detail())
```

## Backend modes

The backend is selected with environment variables.

```text
RANDOMRAD_BACKEND=auto|hw|file
RANDOMRAD_PORT=COM3
RANDOMRAD_BAUD=115200
RANDOMRAD_SERIAL_TIMEOUT=2.0
RANDOMRAD_HW_MAX_CHUNK=1024
RANDOMRAD_HW_BUFFER_FILL=2048
RANDOMRAD_GENERATED_ENTROPY_DIR=generated_entropy
RANDOMRAD_FILE_SIZE=8192
```

### `auto`

The library first tries the ESP32 hardware backend. If the device is not
available, if the port cannot be opened, or if the response is invalid, the
file backend is used automatically.

### `hw`

Only the ESP32 backend is allowed. This is useful when testing the real device
because errors are not hidden by fallback behavior.

### `file`

Only the file backend is used. This is useful for development and automated
tests on machines without an ESP32.

## ESP32 serial protocol

The host sends:

```text
R <n>\n
```

The ESP32 answers:

```text
S <mode>\n
D <n>\n
<n raw bytes>
```

The optional status mode describes the ESP32-internal entropy path:

- `adc`
- `fallback`
- `mixed`

## Included modules

- `randomrad.__init__`: public package surface
- `randomrad.api`: random-like user API
- `randomrad.entropy`: backend selection and fallback logic
- `randomrad.exceptions`: package-specific exceptions
- `randomrad.backends.file_backend`: file fallback backend
- `randomrad.backends.hw_backend`: ESP32 serial backend with buffering

## Limitations

This package is an educational prototype. It is designed to demonstrate
hardware-backed entropy, backend routing and statistical validation workflows.
It should not be treated as certified cryptographic random number generation.
