Metadata-Version: 2.4
Name: quantum-randomness-service
Version: 1.0.0
Summary: A service providing true quantum random numbers from ANU QRNG and other sources
Home-page: https://github.com/yourusername/quantum-randomness-service
Author: Quantum Randomness Service
Author-email: contact@example.com
Project-URL: Bug Reports, https://github.com/yourusername/quantum-randomness-service/issues
Project-URL: Source, https://github.com/yourusername/quantum-randomness-service
Project-URL: Documentation, https://github.com/yourusername/quantum-randomness-service#readme
Keywords: quantum random number generator qrng anu api service
Classifier: Development Status :: 4 - Beta
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.8
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 :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.104.1
Requires-Dist: uvicorn==0.24.0
Requires-Dist: requests==2.31.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: seaborn>=0.13.0
Requires-Dist: plotly>=5.17.0
Requires-Dist: redis>=5.0.1
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiohttp>=3.9.1
Requires-Dist: websockets>=12.0
Requires-Dist: pytest>=7.4.3
Requires-Dist: pytest-asyncio>=0.21.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: redis
Requires-Dist: redis>=4.0.0; extra == "redis"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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. 
