# Quantum Randomness Service
A comprehensive service that provides true quantum random numbers from multiple sources including ANU's Quantum Random Number Generator (QRNG) and configurable custom sources.
## Features
- 🌊 **True Quantum Randomness** - Direct from quantum sources
- 🚀 **High-Performance API** - FastAPI backend with async support
- 📦 **Python Library** - Easy-to-use client library
- 💾 **Smart Caching** - Redis-based caching for performance
- 🔄 **Real-time Streaming** - WebSocket support for live random numbers
- 📊 **Entropy Visualization** - Interactive web interface
- 🔧 **Multiple Sources** - ANU QRNG + configurable sources
- 🛡️ **Cryptographic Quality** - Suitable for security applications
## Installation
### Option 1: Install as a Package (Recommended)
```bash
# Install the package
pip install quantum-randomness-service
# Or install with Redis support
pip install quantum-randomness-service[redis]
# Or install with development dependencies
pip install quantum-randomness-service[dev]
```
### Option 2: Install from Source
```bash
# Clone the repository
git clone https://github.com/yourusername/quantum-randomness-service.git
cd quantum-randomness-service
# Install dependencies
pip install -r requirements.txt
# Install the package in development mode
pip install -e .
```
## Quick Start
### Run the Service
```bash
# Method 1: Using the installed command
quantum-randomness-service
# Method 2: Using the short command
qrandom
# Method 3: Using Python directly
python -m app.main
# Method 4: Using uvicorn
uvicorn app.main:app --reload
```
### Use the Python Library
```python
from qrandom import QuantumRandom, get_random, get_random_batch
# Quick usage with convenience functions
random_number = get_random()
numbers = get_random_batch(10)
# Full client usage
qr = QuantumRandom()
# Synchronous methods
result = qr.get_random_sync()
print(f"Random number: {result['random_number']}")
print(f"Source: {result['source']}")
# Asynchronous methods
import asyncio
async def main():
result = await qr.get_random()
print(f"Random number: {result['random_number']}")
asyncio.run(main())
# Context manager usage
with QuantumRandom() as client:
numbers = client.get_random_numbers(5)
print(f"Numbers: {numbers}")
```
## API Endpoints
- `GET /random` - Get a single random number
- `GET /random/batch?count=100` - Get multiple random numbers
- `GET /random/stream` - WebSocket stream of random numbers
- `GET /stats` - Service statistics and entropy metrics
- `GET /visualize` - Interactive entropy visualization
## Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ANU QRNG │ │ Custom QRNG │ │ Cache Layer │
│ (Primary) │ │ (Fallback) │ │ (Redis) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ API Service │
│ (FastAPI) │
└─────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Python Client │ │ Web Interface │ │ WebSocket API │
│ Library │ │ (Visualization)│ │ (Streaming) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## Use Cases
- **Cryptography**: Generate cryptographic keys and nonces
- **Simulations**: Monte Carlo methods, scientific simulations
- **Gaming**: Fair random number generation
- **Research**: Quantum computing and randomness studies
- **Security**: True randomness for security applications
## Configuration
Create a `.env` file:
```env
ANU_API_URL=https://qrng.anu.edu.au/API/jsonI.php
CACHE_TTL=300
REDIS_URL=redis://localhost:6379
CUSTOM_QRNG_URL=your-custom-qrng-url
```
## Examples
### Basic Usage
```python
from qrandom import get_random, get_random_batch
# Get a single random number
number = get_random()
print(f"Random number: {number}")
# Get multiple random numbers
numbers = get_random_batch(5)
print(f"Random numbers: {numbers}")
```
### Advanced Usage
```python
from qrandom import QuantumRandom
import asyncio
async def main():
client = QuantumRandom()
# Get random number with metadata
result = await client.get_random()
print(f"Number: {result['random_number']}")
print(f"Source: {result['source']}")
print(f"Entropy: {result['entropy_score']}")
# Get service statistics
stats = await client.get_stats()
print(f"Total requests: {stats['total_requests']}")
print(f"Cache hit rate: {stats['cache_hit_rate']}%")
await client.close()
asyncio.run(main())
```
### Error Handling
```python
from qrandom import QuantumRandom
try:
client = QuantumRandom("http://localhost:8000")
result = client.get_random_sync()
print(f"Success: {result}")
except Exception as e:
print(f"Error: {e}")
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/quantum-randomness-service",
"name": "quantum-randomness-service",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "quantum random number generator qrng anu api service",
"author": "Quantum Randomness Service",
"author_email": "contact@example.com",
"download_url": "https://files.pythonhosted.org/packages/ff/de/407c32ff4a39de08f9b7b360d230d85b19c1ce6cc467c4a1f1c5cfdeadaf/quantum_randomness_service-1.0.0.tar.gz",
"platform": null,
"description": "# Quantum Randomness Service\n\nA comprehensive service that provides true quantum random numbers from multiple sources including ANU's Quantum Random Number Generator (QRNG) and configurable custom sources.\n\n## Features\n\n- \ud83c\udf0a **True Quantum Randomness** - Direct from quantum sources\n- \ud83d\ude80 **High-Performance API** - FastAPI backend with async support\n- \ud83d\udce6 **Python Library** - Easy-to-use client library\n- \ud83d\udcbe **Smart Caching** - Redis-based caching for performance\n- \ud83d\udd04 **Real-time Streaming** - WebSocket support for live random numbers\n- \ud83d\udcca **Entropy Visualization** - Interactive web interface\n- \ud83d\udd27 **Multiple Sources** - ANU QRNG + configurable sources\n- \ud83d\udee1\ufe0f **Cryptographic Quality** - Suitable for security applications\n\n## Installation\n\n### Option 1: Install as a Package (Recommended)\n\n```bash\n# Install the package\npip install quantum-randomness-service\n\n# Or install with Redis support\npip install quantum-randomness-service[redis]\n\n# Or install with development dependencies\npip install quantum-randomness-service[dev]\n```\n\n### Option 2: Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/quantum-randomness-service.git\ncd quantum-randomness-service\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install the package in development mode\npip install -e .\n```\n\n## Quick Start\n\n### Run the Service\n\n```bash\n# Method 1: Using the installed command\nquantum-randomness-service\n\n# Method 2: Using the short command\nqrandom\n\n# Method 3: Using Python directly\npython -m app.main\n\n# Method 4: Using uvicorn\nuvicorn app.main:app --reload\n```\n\n### Use the Python Library\n\n```python\nfrom qrandom import QuantumRandom, get_random, get_random_batch\n\n# Quick usage with convenience functions\nrandom_number = get_random()\nnumbers = get_random_batch(10)\n\n# Full client usage\nqr = QuantumRandom()\n\n# Synchronous methods\nresult = qr.get_random_sync()\nprint(f\"Random number: {result['random_number']}\")\nprint(f\"Source: {result['source']}\")\n\n# Asynchronous methods\nimport asyncio\nasync def main():\n result = await qr.get_random()\n print(f\"Random number: {result['random_number']}\")\n\nasyncio.run(main())\n\n# Context manager usage\nwith QuantumRandom() as client:\n numbers = client.get_random_numbers(5)\n print(f\"Numbers: {numbers}\")\n```\n\n## API Endpoints\n\n- `GET /random` - Get a single random number\n- `GET /random/batch?count=100` - Get multiple random numbers\n- `GET /random/stream` - WebSocket stream of random numbers\n- `GET /stats` - Service statistics and entropy metrics\n- `GET /visualize` - Interactive entropy visualization\n\n## Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 ANU QRNG \u2502 \u2502 Custom QRNG \u2502 \u2502 Cache Layer \u2502\n\u2502 (Primary) \u2502 \u2502 (Fallback) \u2502 \u2502 (Redis) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 \u2502 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 API Service \u2502\n \u2502 (FastAPI) \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 \u2502 \u2502\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Python Client \u2502 \u2502 Web Interface \u2502 \u2502 WebSocket API \u2502\n\u2502 Library \u2502 \u2502 (Visualization)\u2502 \u2502 (Streaming) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Use Cases\n\n- **Cryptography**: Generate cryptographic keys and nonces\n- **Simulations**: Monte Carlo methods, scientific simulations\n- **Gaming**: Fair random number generation\n- **Research**: Quantum computing and randomness studies\n- **Security**: True randomness for security applications\n\n## Configuration\n\nCreate a `.env` file:\n\n```env\nANU_API_URL=https://qrng.anu.edu.au/API/jsonI.php\nCACHE_TTL=300\nREDIS_URL=redis://localhost:6379\nCUSTOM_QRNG_URL=your-custom-qrng-url\n```\n\n## Examples\n\n### Basic Usage\n\n```python\nfrom qrandom import get_random, get_random_batch\n\n# Get a single random number\nnumber = get_random()\nprint(f\"Random number: {number}\")\n\n# Get multiple random numbers\nnumbers = get_random_batch(5)\nprint(f\"Random numbers: {numbers}\")\n```\n\n### Advanced Usage\n\n```python\nfrom qrandom import QuantumRandom\nimport asyncio\n\nasync def main():\n client = QuantumRandom()\n \n # Get random number with metadata\n result = await client.get_random()\n print(f\"Number: {result['random_number']}\")\n print(f\"Source: {result['source']}\")\n print(f\"Entropy: {result['entropy_score']}\")\n \n # Get service statistics\n stats = await client.get_stats()\n print(f\"Total requests: {stats['total_requests']}\")\n print(f\"Cache hit rate: {stats['cache_hit_rate']}%\")\n \n await client.close()\n\nasyncio.run(main())\n```\n\n### Error Handling\n\n```python\nfrom qrandom import QuantumRandom\n\ntry:\n client = QuantumRandom(\"http://localhost:8000\")\n result = client.get_random_sync()\n print(f\"Success: {result}\")\nexcept Exception as e:\n print(f\"Error: {e}\")\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details. \n",
"bugtrack_url": null,
"license": null,
"summary": "A service providing true quantum random numbers from ANU QRNG and other sources",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/quantum-randomness-service/issues",
"Documentation": "https://github.com/yourusername/quantum-randomness-service#readme",
"Homepage": "https://github.com/yourusername/quantum-randomness-service",
"Source": "https://github.com/yourusername/quantum-randomness-service"
},
"split_keywords": [
"quantum",
"random",
"number",
"generator",
"qrng",
"anu",
"api",
"service"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4bf50fee71de59b64e8758310cc0b83eff68229e333881db95b7ec37fe41e134",
"md5": "eb58881516466490ccc8d2ec2c32a3d5",
"sha256": "28c7211952fb941be87aff5827b69c5c81eec82188cad3ee03d9e5f8b0a1b3ab"
},
"downloads": -1,
"filename": "quantum_randomness_service-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb58881516466490ccc8d2ec2c32a3d5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48378,
"upload_time": "2025-07-18T02:20:02",
"upload_time_iso_8601": "2025-07-18T02:20:02.733076Z",
"url": "https://files.pythonhosted.org/packages/4b/f5/0fee71de59b64e8758310cc0b83eff68229e333881db95b7ec37fe41e134/quantum_randomness_service-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ffde407c32ff4a39de08f9b7b360d230d85b19c1ce6cc467c4a1f1c5cfdeadaf",
"md5": "a71c7c46ace19b3379c5965572a89173",
"sha256": "29e822a8de4abb5e297eb9be0f6a2dd92551882a12c96f3a43e3260385dc7ec1"
},
"downloads": -1,
"filename": "quantum_randomness_service-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a71c7c46ace19b3379c5965572a89173",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 57798,
"upload_time": "2025-07-18T02:20:04",
"upload_time_iso_8601": "2025-07-18T02:20:04.664236Z",
"url": "https://files.pythonhosted.org/packages/ff/de/407c32ff4a39de08f9b7b360d230d85b19c1ce6cc467c4a1f1c5cfdeadaf/quantum_randomness_service-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 02:20:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "quantum-randomness-service",
"github_not_found": true,
"lcname": "quantum-randomness-service"
}