client_sdk/python/README.md

# QCrypt RNG Python Client SDK

The official Python client SDK for the QCrypt RNG API, providing easy access to quantum random number generation, post-quantum cryptography, and blockchain security features.

## Installation

```bash
pip install qcrypt-client
```

## Quick Start

```python
from qcrypt_client import QCryptClient, Algorithm, OutputFormat

# Initialize client
client = QCryptClient(base_url="https://api.qcrypt.example.com", api_key="your-api-key")

# Generate quantum random bytes
result = client.generate_bytes(length=32, quantum_bits=8, output_format=OutputFormat.HEX)
print(f"Generated bytes: {result['data']['bytes']}")

# Generate a quantum-safe key pair
result = client.generate_pqc_keypair(Algorithm.DILITHIUM3)
print(f"DILITHIUM3 key generated, NIST Level: {result['data']['nist_level']}")

# Assess quantum threat
result = client.assess_quantum_threat("RSA-2048")
print(f"RSA-2048 threat: {result['data']['assessment']['status']}")
```

## Features

- **Quantum Random Generation**: Generate cryptographically secure random bytes using quantum mechanics
- **Cryptographic Keys**: Create AES, RSA, and ECDSA keys with quantum entropy
- **Session Tokens**: Generate secure authentication tokens
- **Quantum UUIDs**: Create unique identifiers with quantum entropy
- **Secure Passwords**: Generate strong passwords with customizable parameters
- **Post-Quantum Cryptography**: Generate NIST-standardized quantum-safe keys (DILITHIUM, KYBER)
- **Blockchain Security**: Create quantum-safe blockchain wallets and simulate quantum attacks
- **Quantum Threat Assessment**: Evaluate vulnerability to quantum attacks

## API Endpoints

### Random Generation
- `generate_bytes()` - Generate quantum random bytes
- `generate_key()` - Create cryptographic keys
- `generate_token()` - Generate session tokens
- `generate_uuid()` - Create quantum UUIDs
- `generate_password()` - Generate secure passwords

### Post-Quantum Cryptography
- `generate_pqc_keypair()` - Generate quantum-safe key pairs
- `sign_with_pqc()` - Sign messages with quantum-safe signatures
- `verify_pqc_signature()` - Verify quantum-safe signatures
- `assess_quantum_threat()` - Evaluate algorithm quantum resistance

### Blockchain Security
- `create_blockchain_wallet()` - Create quantum-safe wallets
- `sign_blockchain_transaction()` - Sign blockchain transactions
- `simulate_quantum_attack()` - Simulate Shor's algorithm attacks

## Configuration

The client accepts the following parameters:

- `base_url`: Base URL of the QCrypt API server (default: "http://localhost:8000")
- `api_key`: API key for authentication (optional if not required)

## Error Handling

All methods raise `QCryptAPIError` for API-related errors. Catch this exception to handle errors gracefully:

```python
try:
    result = client.generate_bytes(length=32)
except QCryptAPIError as e:
    print(f"API Error: {e}")
```

## Security

- All communication with the API is encrypted via HTTPS
- API keys should be stored securely and never exposed in client-side code
- The SDK follows security best practices for handling sensitive data

## Support

For support, please contact us at [support@qcrypt.example.com](mailto:support@qcrypt.example.com) or open an issue in our [GitHub repository](https://github.com/quantumGlobalGroup/qcrypt-rng).

## License

This SDK is released under the MIT License. See the [LICENSE](../LICENSE) file for more details.