Metadata-Version: 2.4
Name: gjq-client
Version: 0.1.0
Summary: Qiskit 2.0 adapter for GuoJi Quantum Cloud Platform
Author: GJQ Cloud Team
License: Apache-2.0
Project-URL: Homepage, https://www.tiangongqs.com
Project-URL: Repository, https://github.com/GuojiQE/GuoJiQE-Client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: qiskit>=2.0.0
Requires-Dist: qiskit-ibm-runtime>=0.44.0
Requires-Dist: python-dateutil>=2.8.0
Dynamic: license-file

# GJQ-Client

`gjq-client` is the Python SDK for the GuoJi Quantum Cloud Platform, providing Qiskit 2.0 integration with real quantum hardware.

## Project Structure

```
src/gjq_client/
├── __init__.py                # Public API exports
├── _version.py                # Version info
├── gjq_runtime/               # Runtime service module
│   ├── gjq_runtime_service.py # Service entry (auth, backend discovery)
│   ├── sampler.py             # Sampler primitive
│   ├── estimator.py           # Estimator primitive
│   └── runtime_job.py         # Job status tracking
├── client/                    # Auth & communication module
│   ├── client_parameters.py   # JWT lifecycle management
│   ├── auth.py                # Auth header injection
│   ├── session.py             # HTTP retry session
│   ├── runtime.py             # REST API client
│   └── rest/                  # REST adapter layer
├── backend/                   # Backend models
│   ├── gjq_backend.py         # GJQBackend (BackendV2)
│   ├── backend_configuration.py
│   └── backend_properties.py
└── utils/                     # Utilities
    ├── exceptions.py          # Exception classes
    ├── backend_converter.py   # Configuration → Target
    ├── backend_decoder.py     # Server data decoder
    └── generate_preset_pass_manager.py
```

## 📦 Installation

Requirements: `Python >= 3.10`, `Qiskit >= 2.0.0`

```bash
# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ gjq-client

# Install from source
pip install .
```

## 🚀 Quick Start

```python
from qiskit import QuantumCircuit
from gjq_client import GJQRuntimeService, Sampler, generate_preset_pass_manager

# 1. Authenticate and initialize RuntimeService
#    (API key required on first use, cached automatically afterwards.
#     Obtain your key from tiangongqs.com/cloud)
service = GJQRuntimeService(api_key="YOUR_API_KEY")

# 2. Select a quantum backend
backend = service.backend("target_quantum_machine")
# Or pick the least busy backend:
# backend = service.least_busy()

# 3. Build a quantum circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# 4. Transpile the circuit for the target backend
pm = generate_preset_pass_manager(backend=backend, optimization_level=2)
transpiled_qc = pm.run(qc)

# 5. Submit the job and retrieve results
sampler = Sampler(backend=backend)
job = sampler.run(transpiled_qc, shots=1024)

result = job.result()
print("Measurement results:", result.get("counts"))
```

## 📄 License

Apache License 2.0
