Metadata-Version: 2.4
Name: qbitshield
Version: 2.3.1
Summary: QbitShield Python SDK — quantum-safe key distribution via Prime Harmonic Modulation
Home-page: https://github.com/Sensorman/qbitshield-v2
Author: QbitShield
Author-email: support@qbitshield.com
License: MIT
Project-URL: Documentation, https://qbitshield-enterprise.vercel.app/documentation
Project-URL: API Reference, https://qbitshield-api.railway.app/docs
Project-URL: Issue Tracker, https://github.com/Sensorman/qbitshield-v2/issues
Keywords: quantum cryptography key-distribution post-quantum security nist prime-harmonics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
Classifier: Programming Language :: Python :: 3
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# QbitShield SDK v2.3.0

Python client for QbitShield's quantum-safe key distribution API — Prime Harmonic Modulation (PHM), patent PCT/US25/39370.

## Installation

```bash
pip install qbitshield
```

## Quick Start

```python
from qbitshield import QbitShieldClient

client = QbitShieldClient(
    api_key="YOUR_API_KEY",
    base_url="https://api.qbitshield.com"
)

result = client.generate_key(security_level=256, enable_nist_validation=True)

print(result.key_id)            # qbit_1780254071056910
print(result.key[:16] + "...")  # first 16 hex chars
print(result.nist_score)        # 7–15 (NIST SP 800-22 tests passed)
print(result.nist_grade)        # A / B / C
print(result.entropy_bits)      # 255.89
print(result.source)            # "aer_simulator" or "ibm_quantum"
print(result.is_quantum)        # True if generated on IBM hardware
print(result.verification_url)  # https://quantum.ibm.com/jobs/<id> or None
```

## Quantum Hardware Provenance

When IBM Quantum Runtime is active, every key includes a verifiable hardware job ID:

```python
result = client.generate_key(security_level=256)

if result.is_quantum:
    print(f"Verified at: {result.verification_url}")
    # https://quantum.ibm.com/jobs/d8e3v607jphs739k6kig
else:
    print(f"Source: {result.source}")  # aer_simulator
```

## PB-QKD (Patent-Aligned Protocol)

```python
from qbitshield import PBQKDClient

pb_client = PBQKDClient(api_key="YOUR_API_KEY")

result = pb_client.generate_key(
    primes=[2, 3, 5, 7, 11],
    times=[0.1, 0.2, 0.3, 0.4, 0.5],
    bases=["Z", "X", "Z", "X", "Z"],
)
print(result.final_key)
print(result.entropy_digest)
```

## Encryption Helpers

```python
# AES-256-GCM encryption using quantum key material
result = client.generate_key(security_level=256)

ciphertext = client.encrypt_message("top secret", result.key, strength=256)
plaintext  = client.decrypt_message(ciphertext,   result.key, strength=256)
```

## Metrics

```python
metrics = client.get_metrics(hours=24)
print(metrics.total_keys_generated)
print(metrics.average_latency_ms)
print(metrics.nist_compliance_rate)
```

## KeyResult Fields

| Field | Type | Description |
|-------|------|-------------|
| `key_id` | str | Unique key identifier |
| `key` | str | Hex-encoded cryptographic key |
| `security_level` | int | 128, 256, or 384 bits |
| `latency_ms` | float | Generation latency |
| `source` | str | `aer_simulator` or `ibm_quantum` |
| `quantum_hardware` | bool | True if generated on IBM hardware |
| `entropy_job_id` | str \| None | IBM Quantum job ID |
| `nist_score` | float \| None | NIST SP 800-22 tests passed (0–15) |
| `nist_grade` | str \| None | A / B / C / F |
| `entropy_bits` | float \| None | Shannon entropy of key material |
| `is_quantum` | bool | Property — alias for `quantum_hardware` |
| `verification_url` | str \| None | Property — IBM job verification link |

## API Base URL

| Environment | URL |
|-------------|-----|
| Production | `https://api.qbitshield.com` |
| Local | `http://localhost:8000` |

Override the default with the `QBITSHIELD_API_BASE` environment variable.

## Research

PHM is backed by 5 peer-reviewed publications:

- [PHM & Riemann Hypothesis Connection](https://zenodo.org/records/20476925) — Zenodo 10.5281/zenodo.20476925
- [Security Bound Theorem](https://eprint.iacr.org/2026/109747) — IACR ePrint 2026/109747
- [Atomic Energy Validation](https://zenodo.org/records/20477083) — Zenodo 10.5281/zenodo.20477083
- [NIST SP 800-22 Implementation](https://eprint.iacr.org/2026/109748) — IACR ePrint 2026/109748
- [IBM Quantum Hardware Results](https://zenodo.org/records/20477312) — Zenodo 10.5281/zenodo.20477312

IBM Quantum hardware experiments (ibm_fez, ibm_kingston) — job IDs verifiable at quantum.ibm.com.

## Resources

- [Enterprise Portal](https://qbitshield.com)
- [API Reference](https://qbitshield.com/documentation/api-reference)
- [Research Publications](https://qbitshield.com/research)
- [GitHub](https://github.com/Sensorman/qbitshield-sdk)

## License

MIT License. See `LICENSE` for details.
