Metadata-Version: 2.4
Name: chaos-rng
Version: 0.1.2
Summary: Chaos-based random number generator using three-body dynamics
Project-URL: Homepage, https://github.com/mustafatarim/chaos-rng
Project-URL: Documentation, https://github.com/mustafatarim/chaos-rng#readme
Project-URL: Repository, https://github.com/mustafatarim/chaos-rng.git
Project-URL: Bug Tracker, https://github.com/mustafatarim/chaos-rng/issues
Author-email: Mustafa Tarim <mail@mustafatarim.com>
License: MIT License
        
        Copyright (c) 2024 Mustafa Tarim
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, so the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: chaos,cryptography,entropy,random,rng,three-body
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Mathematics
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: numba>=0.56.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: all
Requires-Dist: black>=22.0; extra == 'all'
Requires-Dist: build>=1.0; extra == 'all'
Requires-Dist: cryptography>=3.0; extra == 'all'
Requires-Dist: mypy>=1.0; extra == 'all'
Requires-Dist: nistrng>=0.1.0; extra == 'all'
Requires-Dist: pre-commit>=3.0; extra == 'all'
Requires-Dist: pytest-benchmark>=4.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: twine>=4.0; extra == 'all'
Provides-Extra: crypto
Requires-Dist: cryptography>=3.0; extra == 'crypto'
Provides-Extra: dev
Requires-Dist: black>=22.0; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Provides-Extra: docs
Provides-Extra: test
Requires-Dist: nistrng>=0.1.0; extra == 'test'
Requires-Dist: pytest-benchmark>=4.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# Chaos RNG

[![CI](https://github.com/mustafatarim/chaos-rng/actions/workflows/ci.yml/badge.svg)](https://github.com/mustafatarim/chaos-rng/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Chaos RNG is a Python library for generating random numbers from chaotic
three-body dynamics, with NumPy-compatible generators and optional
cryptographic post-processing utilities.

This project is currently documented README-first for the `0.1.x` releases.

## Installation

Core package:

```bash
pip install chaos-rng
```

With optional crypto and test utilities:

```bash
pip install "chaos-rng[crypto,test]"
```

## Quick Start

```python
from chaos_rng import ThreeBodyRNG

rng = ThreeBodyRNG(seed=42)

print(rng.random(5))            # floats in [0, 1)
print(rng.randint(0, 10, 5))    # integers
print(rng.bytes(16).hex())      # raw bytes
```

Notes:

- First calls may be slower because numerical kernels warm up (Numba/JIT).
- Use a fixed `seed` for reproducible tests and experiments.

## NumPy Integration

```python
from chaos_rng.generators import create_chaos_generator

gen = create_chaos_generator(seed=42)

normal = gen.normal(size=1000)
uniform = gen.uniform(0, 10, size=100)
integers = gen.integers(0, 100, size=50)
```

## Optional Crypto Utilities

The `crypto` extra provides helper utilities for secure seeding and
post-processing. These tools are useful for experimentation and integration,
but this project should not be treated as a drop-in replacement for a
security-audited cryptographic RNG.

```python
from chaos_rng import ThreeBodyRNG
from chaos_rng.security import CryptoPostProcessor, SecureSeed

seed = SecureSeed().generate_seed()
rng = ThreeBodyRNG(seed=seed)

raw = rng.bytes(64)
processed = CryptoPostProcessor(method="hash").process(raw)

print(len(processed))
```

## Validation Utilities (Optional / Expensive)

Validation helpers are included under `chaos_rng.utils.validation`. They can be
computationally expensive and are best used for offline analysis.

```python
from chaos_rng import ThreeBodyRNG
from chaos_rng.utils.validation import EntropyValidator

rng = ThreeBodyRNG(seed=42)
bits = (rng.random(10000) * 2).astype(int)

validator = EntropyValidator()
result = validator.validate_entropy_rate(bits)
print(result)
```

`NISTTestSuite` and `ContinuousValidator` are also available, but they are not
part of the default CI gate in `0.1.2`.

## Performance and Caveats

- This library prioritizes clarity and reproducibility over minimal dependency
  footprint (`numpy`, `scipy`, `numba`).
- Some operations are expensive for large sample sizes.
- Cryptographic helpers are optional and not a substitute for audited crypto
  libraries or formal security review.

## Development

Common commands:

```bash
make install-dev
make lint
make test
make test-slow
make build
make check-build
```

Local release gate:

```bash
make release-check
```

## Release Flow (0.1.x)

The intended release path is:

1. Tag release (`v0.1.2`)
2. Publish to TestPyPI
3. Smoke-test install from TestPyPI
4. Publish to PyPI

GitHub Actions workflows:

- `CI` (`.github/workflows/ci.yml`)
- `Release` (`.github/workflows/release.yml`)

## License

MIT License. See [`LICENSE`](LICENSE).
