Metadata-Version: 2.4
Name: jiuzhang-sdk
Version: 0.1.0a10
Summary: 九章光量子真机云接入软件包（jiuzhang SDK）
Author: 九章量子 SDK 团队
License: Proprietary
Keywords: gbs,jiuzhang,photonic,quantum,sdk
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: jupyter
Requires-Dist: ipython>=8; extra == 'jupyter'
Description-Content-Type: text/markdown

# jiuzhang SDK 开发说明

本目录是 `jiuzhang` Python SDK 的源码工程。仓库根 `README.md` 面向用户和外部
协作方，本文件面向 SDK 开发维护。

## 当前主线

当前主线是九章云平台 HTTP SDK：

```text
Python / Jupyter
  -> jiuzhang SDK
  -> 九章云平台 API / 本地九章云平台 Mock
  -> 天衍适配器
  -> 天衍平台 / tianyan-Mock
```

SDK 不直接请求天衍平台，不直接请求 tianyan-Mock，也不保留早期 TCP 真机直连
协议线。

## 工程结构

```text
code/
├── pyproject.toml
├── README.md
├── src/jiuzhang/
│   ├── __init__.py
│   ├── auth/              # TokenManager
│   ├── cloud/             # CloudClient / HttpTransport
│   ├── gbs/               # GBSParams / GBSResult / analysis / mock
│   ├── jupyter.py         # Notebook helpers
│   ├── settings.py        # Settings.from_env()
│   ├── errors.py
│   ├── exceptions.py
│   └── result.py
└── tests/
    ├── unit/
    └── integration/
```

## 本地开发

使用本机 `jzsdk` conda 环境：

```powershell
conda activate jzsdk
cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk\code
pip install -e ".[dev,jupyter]"
```

质量检查：

```powershell
ruff format src tests
ruff check src tests
mypy src
pytest tests
```

## 公开 API

```python
from jiuzhang import CloudClient, TokenManager
from jiuzhang import GBSParams, GBSResult, parse_gbs_result
from jiuzhang.gbs.analysis import photon_count_histogram
from jiuzhang.gbs.mock import generate_mock_samples
```

## 云平台接口

SDK 当前请求九章云平台公开接口：

```text
POST /estimate
POST /tasks/submit
GET  /tasks/{task_id}
```

认证头：

```text
X-Jiuzhang-API-Key: <api_key>
```

提交任务时自动携带：

```text
X-Request-Id: <uuid>
```

所有云平台响应先检查 `code`，只有 `code == 0` 才视为业务成功。

## 本地 Mock

```powershell
cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk
python local_test/mock_cloud_platform/mock_cloud_platform.py --port 18081 --mode standalone
```

SDK 测试和示例中的 `base_url` 指向本地九章云平台 Mock：

```text
http://127.0.0.1:18081
```

## 版本

当前版本：`0.1.0a10`。

## License

Proprietary — Copyright © 2026 九章量子.
