Metadata-Version: 2.4
Name: cortexa-sdk
Version: 0.3.0
Summary: Python SDK for Cortexa: download & parse datasets (JSON/YOLO/COCO), list datasets with template-annotation filter, and structured EvalSample output for evaluation pipelines.
Author: Cortexa
Project-URL: Homepage, https://example.com
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests

---
audience: [engineering, business]
edit_policy: factual_direct
source_of_truth:
  - backend/server/settings.py
  - backend/server/urls.py
  - backend/requirements.txt
  - frontend/package.json
  - 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 立方体检测模型，标注员只需修正
- **一行代码拉数据集**：Python SDK 支持 JSON/YOLO/COCO 格式导出，按标签过滤、按模板分组打包

## 架构

```mermaid
graph TD
    Browser["UmiJS + Ant Design 前端<br/>:8001"]
    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)"]
    SDK["cortexa-sdk<br/>Python CLI + API"]

    Browser -->|HTTP /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 | >= 18 | 前端构建 |
| pnpm | >= 8 | 前端包管理 |
| 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

# 5. 安装 SDK（可选，用于脚本化下载数据集）
pip install cortexa-sdk
cortexa-sdk --init-config                 # 生成 ~/.cortexa/config.json
```

## 仓库结构

| 目录 | 说明 |
|---|---|
| `backend/` | Django REST Framework API 服务（Python 3.10 + MongoDB） |
| `frontend/` | UmiJS + Ant Design 标注 Web 界面（TypeScript + React） |
| `cortexa_sdk/` | 用户侧 Python SDK（`pip install cortexa-sdk`） |

## 文档导航

| 文档 | 说明 |
|---|---|
| [`PRODUCT.md`](PRODUCT.md) | 产品能力总览 |
| [`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/how-to/local-development.md`](docs/how-to/local-development.md) | 本地开发 |
| [`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.
