Metadata-Version: 2.4
Name: qubecli
Version: 1.0.19
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.18
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 서버 (기본 주소: `localhost:50051`)

---

## 설치

```bash
pip install qubecli
```

---

## 빠른 시작

### 1. 서버 주소 설정

```bash
qubecore config set host 192.168.1.100:50051
```

### 2. 로그인

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

### 3. 회로 제출

```bash
qubecore submit \
  --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   : 3f2a1b4c-...
#   priority : NORMAL
```

### 4. 잡 완료 대기 및 결과 확인

```bash
qubecore status --job-id <job_id> --watch

qubecore result --job-id <job_id>
#   job_id : 3f2a1b4c-...
#   status : COMPLETED
#   [circuit 0] counts : {'00': 512, '11': 488}
```

---

## 핵심 개념

### 잡 상태 흐름

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

### 우선순위

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

admin 계정은 항상 우선순위 1로 고정되어 실행됩니다.

---

## 커맨드 레퍼런스

### 전역 옵션

모든 커맨드 앞에 지정할 수 있습니다.

| 옵션 | 설명 |
|------|------|
| `--host <host:port>` | 이번 실행에만 적용할 서버 주소 |
| `-o`, `--output <text\|json>` | 출력 형식 (기본값: `text`) |
| `-v`, `--version` | 버전 출력 |

```bash
# JSON 출력 예시
qubecore -o json status --job-id <ID>
```

---

### 인증

#### `qubecore login`

QubeCore 서버에 로그인하고 자격증명을 `~/.qubecore/config.json`에 저장합니다.

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

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

#### `qubecore logout`

로컬에 저장된 자격증명을 삭제합니다.

```bash
qubecore logout
```

#### `qubecore me`

현재 로그인된 사용자 정보를 출력합니다.

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

---

### 설정

#### `qubecore config set <key> <value>`

설정값을 저장합니다. 현재 지원 키: `host`

```bash
qubecore config set host 192.168.1.100:50051
```

#### `qubecore config get [key]`

저장된 설정을 조회합니다. 키를 생략하면 전체 설정을 출력합니다.

```bash
qubecore config get
qubecore config get host
```

#### `qubecore config unset <key>`

설정값을 삭제합니다.

```bash
qubecore config unset host
```

---

### 잡 제출

#### `qubecore submit`

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

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

```bash
# 기본 제출
qubecore submit --circuit 'OPENQASM 2.0; ...' --shots 1000

# 우선순위 및 최적화 레벨 지정
qubecore submit \
  --circuit 'OPENQASM 2.0; ...' \
  --shots 1000 \
  --priority 2 \
  --optimization-level 1
```

#### `qubecore submit-pulse`

백엔드 전용 펄스 프로그램을 제출합니다. `--pulse`는 QubiC instruction 딕셔너리 배열의 JSON 문자열입니다.

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

**펄스 JSON 포맷**: 각 instruction은 `name` 키를 가지는 딕셔너리입니다.

| instruction | 필드 | 설명 |
|-------------|------|------|
| `delay` | `t` (float, 초), `qubit` | 지정 시간만큼 대기 |
| `barrier` | `qubit` | 동기화 포인트 |
| `X90` | `qubit` | 90° X 회전 펄스 |
| `read` | `qubit` | 측정(readout) |

```bash
# X 게이트 (X90 × 2) + 측정
qubecore submit-pulse \
  --pulse '[{"name":"X90","qubit":"qubit_0"},{"name":"X90","qubit":"qubit_0"},{"name":"barrier","qubit":"qubit_0"},{"name":"read","qubit":"qubit_0"}]' \
  --shots 1000 \
  --priority 1

# 딜레이 후 측정 (T1 측정 등)
qubecore submit-pulse \
  --pulse '[{"name":"X90","qubit":"qubit_0"},{"name":"X90","qubit":"qubit_0"},{"name":"delay","t":1e-5,"qubit":"qubit_0"},{"name":"read","qubit":"qubit_0"}]' \
  --shots 1000
```

#### `qubecore submit-reset`

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

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

```bash
qubecore submit-reset --qubits qubit_0,qubit_1 --shots 100
```

#### `qubecore submit-calibration`

캘리브레이션 잡을 제출합니다. (admin 전용)

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--calibration-type` | string | 필수 | `widescan` 또는 `punchout` |
| `--params` | JSON | 필수 | 캘리브레이션 파라미터 |
| `--priority` | 1–4 | 3 | 잡 우선순위 |

```bash
qubecore submit-calibration \
  --calibration-type widescan \
  --params '{"target_qubits": [0, 1]}'
```

---

### 잡 관리

#### `qubecore status`

잡 상태를 조회합니다. `--watch` 옵션으로 완료될 때까지 폴링할 수 있습니다.

| 옵션 | 타입 | 기본값 | 설명 |
|------|------|--------|------|
| `--job-id` | string | 필수 | 잡 ID |
| `--watch`, `-w` | flag | false | 완료까지 폴링 |
| `--interval` | int | 3 | 폴링 간격 (초, `--watch` 전용) |

```bash
# 단순 조회
qubecore status --job-id <ID>

# 완료까지 대기
qubecore status --job-id <ID> --watch

# 5초 간격으로 폴링
qubecore status --job-id <ID> --watch --interval 5

# JSON 출력 (완료 시 한 번만 출력)
qubecore -o json status --job-id <ID> --watch
```

#### `qubecore result`

완료된 잡의 측정 결과를 조회합니다.

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

```bash
qubecore result --job-id <ID>
#   job_id : 3f2a1b4c-...
#   status : COMPLETED
#   [circuit 0] counts : {'00': 512, '11': 488}
```

> 잡이 아직 PENDING 또는 RUNNING 상태이면 오류가 반환됩니다. `qubecore status --watch`로 완료를 확인한 뒤 사용하세요.

#### `qubecore cancel`

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

```bash
qubecore cancel --job-id <ID>
```

#### `qubecore jobs`

내 잡 목록을 페이지 단위로 조회합니다.

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

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

---

### 스트리밍

#### `qubecore stream`

파라미터 스윕을 양방향 스트리밍으로 실행합니다. 회로 템플릿에 `{param}` 형식의 플레이스홀더를 사용합니다.

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

```bash
qubecore 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 정보

#### `qubecore backend-info`

백엔드 이름, 큐비트 수, 커플링 맵, 지원 게이트를 조회합니다.

```bash
qubecore backend-info
#   name                 : kreo.sc-20
#   num_qubits           : 20
#   native_gates         : ['cx', 'u']
#   qasm_supported_gates : ['h', 'cx', 'rx', ...]
#   coupling_map         : [[0, 1], [1, 2], ...]
```

#### `qubecore characterization`

각 큐비트의 T1, T2, 주파수 등 캐릭터라이제이션 데이터를 조회합니다.

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

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

큐비트 캐릭터라이제이션 데이터를 업데이트합니다.

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

#### `qubecore update-qchip` (admin)

QChip 파라미터(주파수, 게이트 설정 등)를 업데이트합니다.

```bash
qubecore update-qchip --updates '[
  {
    "qubit": "qubit_0",
    "freq": 4.85e9,
    "readfreq": 6.5e9,
    "gates": [{"gate_name": "X90", "amp": 0.5, "twidth": 20e-9}]
  }
]'
```

---

### 도움말

#### `qubecore help`

모든 커맨드와 사용 예제를 한 번에 출력합니다.

```bash
qubecore help
```

---

## 문제 해결

| 오류 메시지 | 원인 | 해결 방법 |
|------------|------|-----------|
| `Cannot connect to server` | 서버 주소 불일치 또는 서버 미실행 | `qubecore config set host <host:port>` 로 주소 확인 |
| `Not logged in. Run 'qubecore login' first.` | 자격증명 없음 | `qubecore login` 실행 |
| `Session expired. Run 'qubecore login' again.` | refresh token 만료 | `qubecore login` 재실행 |
| `Authentication failed.` | 잘못된 토큰 | `qubecore logout` 후 재로그인 |
| `Permission denied` | 권한 부족 (admin 전용 커맨드) | admin 계정으로 로그인 |
| `result` 실행 시 오류 | 잡이 아직 완료되지 않음 | `qubecore status --job-id <ID> --watch` 로 완료 확인 후 재시도 |
| `priority must be between 1 and 4` | 잘못된 우선순위 값 | `--priority` 에 1–4 사이 값 사용 |
