Metadata-Version: 2.4
Name: qubecli
Version: 1.0.30
Summary: QubeCore CLI — Command Line Interface for QubeCore
License: MIT License
        
        Copyright (c) 2026 QubeCore Project
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: qubecore-client>=1.0.20
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# QubeCLI

QubeCore — Quantum Computing Operating System을 위한 커맨드라인 인터페이스입니다.  
게이트 회로 제출, 잡 상태 조회, QPU 캘리브레이션 관리 등 QubeCore의 모든 기능을 터미널에서 사용할 수 있습니다.

---

## 사전 조건

- Python 3.11 이상
- 실행 중인 QubeCore gRPC 서버

---

## 설치

```bash
pip install qubecli
```

---

## 빠른 시작

### 1. 서버 연결

```bash
qubecli connect 192.168.1.100:50051
# ✓ Connected to 192.168.1.100:50051
```

### 2. 로그인

```bash
qubecli login
# Username: admin
# Password: ****
```

### 3. 회로 제출

```bash
qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q->c;' \
  --shots 1000
# ✓ Job submitted
#   job_id   : a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   priority : NORMAL
```

### 4. 잡 상태 및 결과 확인

```bash
qubecli status --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

qubecli result --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   job_id : a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   status : COMPLETED
#   [circuit 0] counts : {'00': 512, '11': 488}
```

---

## 핵심 개념

### 잡 상태 흐름

```
PENDING → RUNNING → COMPLETED
                  ↘ FAILED
       ↘ CANCELLED  (취소는 PENDING 상태에서만 가능)
```

### 우선순위

| 값 | 레이블 | 설명 |
|----|--------|------|
| `1` | CRITICAL | 최우선 실행 (admin 전용) |
| `2` | HIGH | 높은 우선순위 |
| `3` | NORMAL | 기본값 |
| `4` | LOW | 낮은 우선순위 |

---

## 커맨드 레퍼런스

### 전역 옵션

| 옵션 | 설명 |
|------|------|
| `-v`, `--version` | 버전 출력 |

---

### 서버 연결

#### `qubecli connect <host[:port]>`

QubeCore 서버에 연결하고 주소를 저장합니다. 연결에 실패하면 에러를 출력합니다.

```bash
qubecli connect localhost:50051
qubecli connect 192.168.1.100:50051
qubecli connect myserver.com
```

---

### 인증

#### `qubecli login`

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--username` | string | (프롬프트) | 사용자 이름 |
| `--password` | string | (프롬프트) | 비밀번호 (입력 시 숨김 처리) |

```bash
qubecli login
qubecli login --username admin --password Admin1234!
```

#### `qubecli logout`

```bash
qubecli logout
```

#### `qubecli me`

```bash
qubecli me
#   user_id    : 1
#   username   : admin
#   role       : admin
#   created_at : 2026-01-01T00:00:00Z
```

---

### 잡 제출

#### `qubecli submit-gate`

게이트 회로(QASM 2.0 / 3.0 / JSON)를 QPU에 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--circuit` | string | 필수 | 회로 문자열 |
| `--shots` | int | 필수 | 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |
| `--optimization-level` | 0–3 | — | 트랜스파일 최적화 레벨 |

```bash
qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q->c;' \
  --shots 1000

qubecli submit-gate \
  --circuit 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q->c;' \
  --shots 1000 --priority 2 --optimization-level 1
```

#### `qubecli submit-pulse`

백엔드 전용 펄스 프로그램을 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--pulse` | string | 필수 | 펄스 프로그램 JSON 문자열 |
| `--shots` | int | 필수 | 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |

```bash
qubecli submit-pulse \
  --pulse '[{"name":"X90","qubit":"qubit_0"},{"name":"read","qubit":"qubit_0"}]' \
  --shots 1000
```

#### `qubecli reset`

큐비트 액티브 리셋 잡을 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--qubits` | string | 필수 | 쉼표로 구분된 큐비트 이름 |
| `--shots` | int | 필수 | 리셋 후 검증 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |

```bash
qubecli reset --qubits qubit_0,qubit_1 --shots 100
```

#### `qubecli widescan` (admin)

주파수 범위 스캔 캘리브레이션 잡을 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--qubit` | string | 필수 | 큐비트 이름 |
| `--span` | float | 100000000 | 주파수 스캔 범위 (Hz) |
| `--n-points` | int | 200 | 스캔 포인트 수 |
| `--num-shots` | int | 100 | 포인트당 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |

```bash
qubecli widescan --qubit qubit_0
qubecli widescan --qubit qubit_0 --span 100000000 --n-points 200 --num-shots 100
```

#### `qubecli punchout` (admin)

Readout Amplitude 스캔 캘리브레이션 잡을 제출합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--qubit` | string | 필수 | 큐비트 이름 |
| `--res-freq` | float | 필수 | 공진 주파수 (Hz) |
| `--amps` | JSON array | 필수 | 스캔할 진폭 리스트 |
| `--span` | float | 20000000 | 주파수 스캔 범위 (Hz) |
| `--n-freqs` | int | 20 | 주파수 포인트 수 |
| `--num-shots` | int | 100 | 포인트당 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |

```bash
qubecli punchout --qubit qubit_0 --res-freq 6450000000 --amps '[0.01,0.05,0.1,0.2,0.3,0.5]'
```

---

### 잡 관리

#### `qubecli status`

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--job-id` | string | 필수 | 잡 ID |

```bash
qubecli status --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

#### `qubecli result`

```bash
qubecli result --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   job_id : a1b2c3d4-e5f6-7890-abcd-ef1234567890
#   status : COMPLETED
#   [circuit 0] counts : {'00': 512, '11': 488}
```

#### `qubecli cancel`

PENDING 상태의 잡을 취소합니다.

```bash
qubecli cancel --job-id a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

#### `qubecli jobs`

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--page` | int | 1 | 페이지 번호 (1-based) |
| `--size` | int | 20 | 페이지당 결과 수 |

```bash
qubecli jobs
qubecli jobs --page 2 --size 10
```

---

### 스트리밍

#### `qubecli stream`

파라미터 스윕을 양방향 스트리밍으로 실행합니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--template` | string | 필수 | `{param}` 플레이스홀더가 포함된 QASM 템플릿 |
| `--params` | JSON array | 필수 | 파라미터 딕셔너리 배열 |
| `--shots` | int | 필수 | 이터레이션당 측정 횟수 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |
| `--optimization-level` | 0–3 | — | 트랜스파일 최적화 레벨 |

```bash
qubecli stream \
  --template 'OPENQASM 2.0; include "qelib1.inc"; qreg q[1]; creg c[1]; rx({theta}) q[0]; measure q[0]->c[0];' \
  --params '[{"theta": 0.0}, {"theta": 1.5707}, {"theta": 3.1415}]' \
  --shots 200
# Streaming 3 iteration(s) → shots=200
#   [1/3] counts={'0': 200}
#   [2/3] counts={'0': 102, '1': 98}
#   [3/3] counts={'1': 200}
```

---

### QPU 정보

#### `qubecli qpu-info`

```bash
qubecli qpu-info
#   name                 : kreo.sc-20
#   num_qubits           : 20
#   native_gates         : ['cx', 'u']
#   coupling_map         : [[0, 1], [1, 2], [2, 3], ...]
```

#### `qubecli characterization`

```bash
qubecli characterization
#   last_calibrated : 2026-05-13T00:00:00Z
#   index  t1           t2           frequency
#   ────── ──────────── ──────────── ────────────
#   0      1.10e-04     9.80e-05     4.8500e+09
```

#### `qubecli update-characterization` (admin)

```bash
qubecli update-characterization --data '{
  "last_calibrated": "2026-05-13T00:00:00Z",
  "qubits": [{"index": 0, "t1": 1.1e-4, "t2": 9.8e-5, "frequency": 4.85e9}]
}'
```


---

## 문제 해결

| 오류 메시지 | 원인 | 해결 방법 |
|------------|------|-----------|
| `No server connected.` | connect 미실행 | `qubecli connect <host:port>` 실행 |
| `Cannot connect to server` | 서버 미실행 또는 주소 불일치 | 서버 실행 여부 확인 후 `qubecli connect <host:port>` 로 재연결 |
| `Not logged in.` | 자격증명 없음 | `qubecli login` 실행 |
| `Session expired.` | refresh token 만료 | `qubecli login` 재실행 |
| `Authentication failed.` | 잘못된 토큰 | `qubecli logout` 후 재로그인 |
| `Permission denied` | 권한 부족 (admin 전용 커맨드) | admin 계정으로 로그인 |
| `priority must be between 1 and 4` | 잘못된 우선순위 값 | `--priority` 에 1–4 사이 값 사용 |
