quantum-randomness-service 1.0.0

A service providing true quantum random numbers from ANU QRNG and other sources

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)

# 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

# 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

# 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

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:

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

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

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

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.