quantum-randomness-service


Namequantum-randomness-service JSON
Version 1.0.0 PyPI version JSON
download
home_pagehttps://github.com/yourusername/quantum-randomness-service
SummaryA service providing true quantum random numbers from ANU QRNG and other sources
upload_time2025-07-18 02:20:04
maintainerNone
docs_urlNone
authorQuantum Randomness Service
requires_python>=3.8
licenseNone
keywords quantum random number generator qrng anu api service
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 2.07929s