cortexa-v2-sdk 0.1.0__tar.gz

cortexa_v2_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: cortexa_v2_sdk
+Version: 0.1.0
+Summary: Python SDK for querying published Cortexa archives and downloading immutable archive or dataset exports.
+Author: Cortexa
+Project-URL: Homepage, https://github.com/verteklab/cortexa
+Project-URL: Repository, https://github.com/verteklab/cortexa
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+
+# Cortexa V2 SDK
+
+`cortexa_v2_sdk` 让训练平台通过稳定的 Python API 查询数基已发布归档，并在 Ray Worker 开训时按不可变 `archive_id` 下载训练数据。发行包使用新名称，Python 导入路径仍为 `cortexa_sdk`，CLI 命令仍为 `cortexa-sdk`。列表发现不依赖共享数据库、对象存储扫描或 `manifest.json`。
+
+## 运行要求
+
+- Python 3.10 或更高版本
+- 可访问 Cortexa API
+- 有效的 Cortexa API Key
+
+## 安装
+
+安装正式版本：
+
+```bash
+python3 -m pip install "cortexa_v2_sdk==0.1.0"
+```
+
+仓库内开发安装：
+
+```bash
+git clone https://github.com/verteklab/cortexa.git
+cd cortexa
+python3 -m pip install -e .
+```
+
+验证：
+
+```bash
+python3 -c "from importlib.metadata import version; print(version('cortexa_v2_sdk'))"
+# 期望输出：0.1.0
+```
+
+## 配置
+
+配置优先级固定为：函数参数 > JSON 配置文件 > 环境变量。
+
+### 环境变量
+
+```bash
+export CORTEXA_API_KEY="<API Key>"
+export CORTEXA_BASE_URL="https://cortexa.example.com/api/v1"
+export CORTEXA_DATASET_DIR="/data/ray_dataset_zip_cache"
+```
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `CORTEXA_API_KEY` | 是 | 请求头 `X-API-KEY` 的值 |
+| `CORTEXA_BASE_URL` | 是 | Cortexa v1 API 基址；SDK 自动从 `/api/v1` 派生归档 `/api/v2` 地址 |
+| `CORTEXA_DATASET_DIR` | 否 | 默认下载目录，缺省为 `~/.cortexa/datasets` |
+| `CORTEXA_CONFIG` | 否 | JSON 配置路径，缺省为 `~/.cortexa/config.json` |
+
+### 配置文件
+
+生成模板：
+
+```bash
+cortexa-sdk --init-config
+```
+
+编辑 `~/.cortexa/config.json`：
+
+```json
+{
+  "api_key": "<API Key>",
+  "base_url": "https://cortexa.example.com/api/v1",
+  "dataset_dir": "/data/ray_dataset_zip_cache"
+}
+```
+
+不要把 API Key 提交到 Git、镜像或训练任务配置中；通过部署环境或密钥管理服务注入。
+
+## 查询训练可用归档
+
+数基归档详情选择“同步到鼎算”时只发布归档引用，不预生成 ZIP。鼎算后端通过 SDK 查询这个列表：
+
+```python
+from cortexa_sdk import CortexaClient
+
+client = CortexaClient()
+result = client.list_training_archives(
+    keyword="桥梁",
+    page=1,
+    page_size=20,
+)
+
+for archive in result["list"]:
+    print(
+        archive["_id"],
+        archive["name"],
+        archive.get("dataset_id"),
+        archive.get("display", {}).get("format"),
+    )
+```
+
+返回分页结构：
+
+```json
+{
+  "list": [
+    {
+      "_id": "归档ID",
+      "dataset_id": "来源数据集ID",
+      "name": "桥梁病害检测",
+      "status": "approved",
+      "display": {
+        "registered": true,
+        "training_name": "桥梁病害训练集",
+        "format": "YOLO",
+        "samples": 8600,
+        "version": "v1.0"
+      }
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+训练平台必须保存 `_id` 作为 `archive_id`。`dataset_id` 只用于来源追溯，不能替代不可变归档 ID。
+
+## 读取归档详情
+
+```python
+archive = client.archive_detail("<archive_id>")
+print(archive["name"])
+print(archive["asset_snapshot"])
+```
+
+训练平台应先从 `list_training_archives()` 取得可用 ID，再读取详情。直接知道归档 ID 不等于该归档已发布给训练平台。
+
+## Ray Worker 按需下载
+
+Worker 开训时按 `archive_id` 请求训练格式。该调用会在数基创建或复用普通归档导出任务，等待任务完成并把 ZIP 下载到本地；它不会创建跨平台 manifest 或共享存储副本。
+
+使用客户端：
+
+```python
+from cortexa_sdk import CortexaClient, ExportType
+
+client = CortexaClient()
+zip_path = client.download_archive(
+    archive_id="<archive_id>",
+    export_type=ExportType.YOLO,
+    split_ratio="8:2",
+    download_dir="/data/ray_dataset_zip_cache",
+    assets_included=True,
+)
+print(zip_path)
+```
+
+Ray Worker 也可以调用模块级函数：
+
+```python
+from cortexa_sdk import ExportType, download_archive
+
+zip_path = download_archive(
+    archive_id="<archive_id>",
+    export_type=ExportType.COCO,
+    split_ratio="7:3",
+    api_key="<API Key>",
+    base_url="https://cortexa.example.com/api/v1",
+    download_dir="/data/ray_dataset_zip_cache",
+)
+```
+
+归档训练下载只支持：
+
+- 格式：`ExportType.YOLO`、`ExportType.COCO`
+- 划分：`8:2`、`7:3`、`9:1`
+
+同一 Worker 节点应按 `archive_id` 复用本地缓存，避免多个训练进程重复下载。
+
+## 下载旧数据集
+
+旧流程仍可按 `dataset_id` 下载：
+
+```python
+from cortexa_sdk import AnnotationType, ExportType, download_dataset
+
+zip_path = download_dataset(
+    dataset_id="<dataset_id>",
+    export_type=ExportType.JSON,
+    annotation_type=AnnotationType.RECT,
+    assets_included=True,
+)
+```
+
+CLI 当前只支持旧 `dataset_id` 下载，不支持归档列表和 `archive_id` 下载：
+
+```bash
+cortexa-sdk \
+  --dataset-id "<dataset_id>" \
+  --export-type YOLO \
+  --annotation-type rect \
+  --download-dir ./tmp/datasets
+```
+
+归档发现和归档下载必须使用 Python API。
+
+## 解析下载包
+
+```python
+from cortexa_sdk.parser import extract_zip, load_dataset
+
+dataset_dir = extract_zip("./tmp/datasets/<dataset_id>.zip")
+samples = load_dataset(dataset_dir)
+print(f"samples={len(samples)}")
+```
+
+`load_dataset()` 返回结构化 `EvalSample` 列表，可读取样本 split、媒体路径和问答标注。
+
+## 异常处理
+
+```python
+from cortexa_sdk import CortexaClient, ExportType
+
+try:
+    client = CortexaClient()
+    path = client.download_archive(
+        "<archive_id>",
+        export_type=ExportType.YOLO,
+    )
+except ValueError as exc:
+    # 配置、格式或划分参数错误
+    print(exc)
+except RuntimeError as exc:
+    # Cortexa 返回业务错误或导出任务失败
+    print(exc)
+```
+
+HTTP 连接、鉴权和超时错误由 `requests` 异常体系抛出。生产 Worker 应让任务框架记录异常并按任务策略重试，不要把失败当作空数据集继续训练。
+
+## 发布到 PyPI
+
+PyPI 上的版本不可覆盖。`cortexa_v2_sdk` 是独立于 `cortexa-sdk` 的新发行包，版本从 `0.1.0` 开始；后续发布前必须把 `pyproject.toml` 中的版本改为一个从未上传过的新版本。
+
+### 1. 准备发布提交
+
+```bash
+git checkout <release-branch>
+python3 -m pytest -q cortexa_sdk/test_sdk.py
+black .
+python3 .docsmith/scripts/gen.example.py
+git diff --check
+```
+
+确认 `pyproject.toml`、SDK 源码、测试和文档属于同一提交，然后提交：
+
+```bash
+git add -p
+git diff --cached --name-only
+git diff --cached --check
+git commit -m "chore(sdk): release cortexa_v2_sdk 0.1.0"
+```
+
+逐项确认暂存内容只包含本次 SDK 版本、源码、测试和受影响文档。仓库存在其他未提交改动时，不要使用 `git add .` 或暂存整个目录。
+
+### 2. 构建并校验产物
+
+```bash
+RELEASE_DIR="$(mktemp -d)"
+python3 -m build --outdir "$RELEASE_DIR"
+python3 -m twine check "$RELEASE_DIR"/*
+ls -lh "$RELEASE_DIR"
+```
+
+期望生成：
+
+- `cortexa_v2_sdk-0.1.0-py3-none-any.whl`
+- `cortexa_v2_sdk-0.1.0.tar.gz`
+- Twine 输出 `PASSED`
+
+使用隔离环境安装 wheel：
+
+```bash
+python3 -m venv /tmp/cortexa-v2-sdk-release-venv
+/tmp/cortexa-v2-sdk-release-venv/bin/python -m pip install \
+  "$RELEASE_DIR/cortexa_v2_sdk-0.1.0-py3-none-any.whl"
+/tmp/cortexa-v2-sdk-release-venv/bin/python -c \
+  "from cortexa_sdk import CortexaClient, download_archive; from importlib.metadata import version; print(version('cortexa_v2_sdk'))"
+```
+
+期望输出 `0.1.0`，且导入不报错。
+
+### 3. TestPyPI 验证
+
+在 TestPyPI 创建 API Token，并只放在当前终端环境中：
+
+```bash
+export TWINE_USERNAME="__token__"
+read -s TWINE_PASSWORD
+export TWINE_PASSWORD
+python3 -m twine upload \
+  --repository-url https://test.pypi.org/legacy/ \
+  "$RELEASE_DIR"/*
+```
+
+从 TestPyPI 安装时，运行依赖仍从正式 PyPI 获取：
+
+```bash
+python3 -m venv /tmp/cortexa-v2-sdk-testpypi-venv
+/tmp/cortexa-v2-sdk-testpypi-venv/bin/python -m pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  "cortexa_v2_sdk==0.1.0"
+```
+
+### 4. 正式发布并打标签
+
+确认 TestPyPI 安装和 SDK 冒烟调用正常后，上传同一目录中的原始产物，不要重新构建：
+
+```bash
+git push origin HEAD
+python3 -m twine upload "$RELEASE_DIR"/*
+unset TWINE_PASSWORD TWINE_USERNAME
+
+git tag -a cortexa-v2-sdk-v0.1.0 -m "cortexa_v2_sdk 0.1.0"
+git push origin cortexa-v2-sdk-v0.1.0
+```
+
+验证正式版本：
+
+```bash
+python3 -m pip index versions cortexa_v2_sdk
+python3 -m pip install --no-cache-dir "cortexa_v2_sdk==0.1.0"
+```
+
+## 发版检查表
+
+- [ ] `pyproject.toml` 版本未在 PyPI 使用
+- [ ] SDK 测试全部通过
+- [ ] `black .`、docsmith 和 `git diff --check` 通过
+- [ ] wheel 与 sdist 均通过 `twine check`
+- [ ] 隔离环境可导入 SDK，版本正确
+- [ ] TestPyPI 安装及关键 API 冒烟通过
+- [ ] 正式 PyPI 上传的是已经验证过的同一批产物
+- [ ] 已推送 `sdk-v<version>` 标签
+- [ ] API Token 未写入文件、命令参数、提交或日志

cortexa_v2_sdk-0.1.0/README.md

@@ -0,0 +1,157 @@
+---
+audience: [engineering, business]
+edit_policy: factual_direct
+source_of_truth:
+  - backend/server/settings.py
+  - backend/server/urls.py
+  - backend/requirements.txt
+  - frontend/package.json
+  - frontend_v2/package.json
+  - frontend_v2/.umirc.ts
+  - {dir: frontend_v2/src/}
+  - {dir: cortexa_sdk/}
+  - {dir: eval/}
+  - pyproject.toml
+  - .docsmith/features.yml
+  - {fact: "仓库结构与开发者入口"}
+---
+
+<!--
+Copyright (c) 2025 Vortek Inc. and Tuanliu (Hainan Special Economic Zone) Technology Co., Ltd.
+All rights reserved.
+-->
+
+# Cortexa
+
+**把原始图片和视频变成可训练数据集**：上传素材、标注（人工或 AI 预标注）、审查、打包导出，一条线走完。
+
+- **多种标注类型**：矩形框、多边形、3D 立方体、折线、自定义答题模板，覆盖检测/分割/3D/质检场景
+- **AI 预标注加速**：接入 PaddleX 小目标检测、SAM2/SAM3 语义分割、3D-MOOD 立方体检测模型，并支持模板 AI 按组生成答案建议，标注员确认后保存
+- **一行代码拉数据集**：Python SDK 支持 JSON/YOLO/COCO/LabelMe 格式导出，也能查询已发布归档，并在 Ray Worker 开训时按 `archive_id` 临时生成和下载训练数据
+
+## 架构
+
+```mermaid
+graph TD
+    Browser["UmiJS + Ant Design 旧前端<br/>:8001"]
+    BrowserV2["React + Umi + Arco v2 工作台<br/>:8002"]
+    API["Django REST Framework<br/>:8000"]
+    Worker["Celery Worker"]
+    Beat["Celery Beat"]
+    Mongo[(MongoDB)]
+    MinIO[(MinIO 对象存储)]
+    RabbitMQ[(RabbitMQ)]
+    AI["AI 模型服务<br/>(PaddleX / SAM2 / SAM3 / 3D-MOOD / 模板 AI)"]
+    SDK["cortexa_v2_sdk<br/>Python CLI + API"]
+
+    Browser -->|HTTP /api/v1/| API
+    BrowserV2 -->|/api/v2/* + 复用 /api/v1/*| API
+    SDK -->|HTTP /api/v1/| API
+    API --> Mongo
+    API --> MinIO
+    API --> RabbitMQ
+    RabbitMQ --> Worker
+    Beat -->|定时任务| RabbitMQ
+    Worker --> Mongo
+    Worker --> MinIO
+    Worker --> AI
+```
+
+## 前置条件
+
+| 依赖 | 版本 | 用途 |
+|---|---|---|
+| Python | >= 3.10 | 后端运行时 |
+| Node.js | >= 20 | 前端构建（含 v2） |
+| pnpm | >= 10.33.0 | 前端包管理 |
+| MongoDB | >= 6 | 主数据库 |
+| MinIO | 最新 | 对象存储（图片/视频/zip） |
+| RabbitMQ | >= 3.12 | Celery 消息队列 |
+
+## 快速启动
+
+```bash
+# 1. 克隆仓库
+git clone <repo-url> && cd cortexa
+
+# 2. 启动后端
+cd backend
+cp .env.example .env          # 填写 MongoDB / MinIO / RabbitMQ 地址
+python3 -m venv venv && source venv/bin/activate
+pip install -r requirements.txt
+python manage.py runserver 0.0.0.0:8000   # API 服务
+
+# 3. 启动 Celery（另开两个终端）
+celery -A server worker -l info           # 异步任务处理
+celery -A server beat -l info             # 定时任务调度
+
+# 4. 启动当前生产前端
+cd ../frontend
+pnpm install && pnpm dev                  # 开发模式，访问 http://localhost:8001
+
+# 或启动 v2 工作台（质检验收按角色显示，其余入口按下列顺序排列）
+# 首页、数据管理、数据标注、数据归档、质检验收、标注类型管理、AI 模型适配、AI 标签映射、人员绩效
+cd ../frontend_v2
+pnpm install
+API_URL=http://127.0.0.1:8000 pnpm dev
+# 开发模式，先访问 http://localhost:8002/login
+# API_URL 由 Umi define 注入，v2 请求会访问 http://127.0.0.1:8000/api
+# 使用管理员账号登录后进入 http://localhost:8002/home
+# V2 登录沿用旧前端的会话键：cortexa_token、cortexa_userInfo、可选 PhilVault token 与 roleList
+
+# 首次启用 v2：先将数据记录集合改名为 asset_packages（可重复执行）
+cd ../backend
+python scripts/migrate_data_records_to_asset_packages.py
+
+# 再为历史根目录创建 raw 数据包记录（可重复执行）
+cd ../backend
+python scripts/migrate_root_folders_to_data_records.py
+
+# 最后为历史数据包回填列表统计投影（可重复执行）
+# V2 列表的筛选、分页和聚合只读统计侧表；切换流量前必须确认 skipped=0
+python scripts/rebuild_asset_package_statistics.py
+
+# 5. 安装 SDK（可选，用于脚本化下载数据集）
+pip install cortexa_v2_sdk
+cortexa-sdk --init-config                 # 生成 ~/.cortexa/config.json
+```
+
+## 仓库结构
+
+| 目录 | 说明 |
+|---|---|
+| `backend/` | Django REST Framework API 服务（Python 3.10 + MongoDB） |
+| `frontend/` | UmiJS + Ant Design 标注 Web 界面（TypeScript + React） |
+| `frontend_v2/` | React + TypeScript + Umi Core + Arco Design；依次提供首页、数据管理、数据标注、数据归档、质检验收、标注类型管理、AI 模型适配、AI 标签映射和人员绩效，其中质检验收按角色显示；覆盖数据包创建、深度校验、增量升版、移动/导出、标注导入回写、全量绩效聚合及图片、视频、多模态抽检复核；外部已标注导入复用 `/api/v1/dataset`，V2 关联项目维护既有 `datasets` 模型 |
+| `cortexa_sdk/` | 用户侧 Python SDK（`pip install cortexa_v2_sdk`）：查询已发布归档、按 `archive_id` 下载训练数据，以及旧数据集下载和解析 |
+| `eval/` | 数据集准备 CLI（`python -m eval`）：列出、下载并解析为 `eval_samples.json` |
+
+`frontend_v2` 通过 Umi qiankun `slave` 模式嵌入统一门户，直接消费门户发布在共享文档根节点上的语义主题 token，并即时跟随浅色/深色预设；独立运行在 `localhost:8002` 且没有兼容主题键时默认使用内置浅色回退值。
+
+## 文档导航
+
+| 文档 | 说明 |
+|---|---|
+| [`PRODUCT.md`](PRODUCT.md) | 产品能力总览 |
+| [`cortexa_sdk/README.md`](cortexa_sdk/README.md) | SDK 安装、配置、归档 API、Ray Worker 接入与 PyPI 发版流程 |
+| [`docs/product/feature-map.md`](docs/product/feature-map.md) | 完整能力矩阵 |
+| [`docs/reference/api.md`](docs/reference/api.md) | HTTP 接口清单 |
+| [`docs/reference/config.md`](docs/reference/config.md) | 环境变量配置参考 |
+| [`docs/reference/data-model.md`](docs/reference/data-model.md) | 数据模型 |
+| [`docs/reference/glossary.md`](docs/reference/glossary.md) | 术语表 |
+| [`docs/reference/ui-design.md`](docs/reference/ui-design.md) | v2 UI 设计与 Arco 组件规范 |
+| [`docs/how-to/local-development.md`](docs/how-to/local-development.md) | 本地开发 |
+| [`docs/how-to/v2-platform-operation-manual.md`](docs/how-to/v2-platform-operation-manual.md) | 数据管理平台 V2 用户操作手册 |
+| [`docs/how-to/deploy.md`](docs/how-to/deploy.md) | 部署 |
+| [`docs/how-to/troubleshooting.md`](docs/how-to/troubleshooting.md) | 排障 |
+| [`docs/explanation/architecture.md`](docs/explanation/architecture.md) | 架构设计 |
+
+## Contributing
+
+1. 从 `main` 拉分支，命名 `feat/xxx` 或 `fix/xxx`
+2. 后端改完跑 `pytest`，前端改完跑 `pnpm build`
+3. 提 PR 并填写 `.github/pull_request_template.md` 模板
+
+## License
+
+Copyright (c) 2025 Vortek Inc. and Tuanliu (Hainan Special Economic Zone) Technology Co., Ltd. All rights reserved.