sinan-captcha 0.1.0__tar.gz

sinan_captcha-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: sinan-captcha
+Version: 0.1.0
+Summary: Training and data engineering workspace for graphical captcha models.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: train
+Requires-Dist: matplotlib; extra == "train"
+Requires-Dist: numpy; extra == "train"
+Requires-Dist: opencv-python; extra == "train"
+Requires-Dist: pandas; extra == "train"
+Requires-Dist: pillow; extra == "train"
+Requires-Dist: pyyaml; extra == "train"
+Requires-Dist: scikit-image; extra == "train"
+Requires-Dist: tqdm; extra == "train"
+Requires-Dist: ultralytics; extra == "train"
+
+# sinan-captcha
+
+`sinan-captcha` 是一个本地训练工程，用来生成和训练两类行为验证码模型：
+
+- `group1`：图形点选
+- `group2`：滑块缺口定位
+
+项目对外只保留两个正式入口：
+
+- `sinan-generator`
+  - Go CLI
+  - 负责固定工作区、素材导入/同步、原始样本生成、批次 QA、YOLO 数据集导出
+- `sinan`
+  - Python CLI
+  - 负责训练目录初始化、素材包构建、JSONL 校验、YOLO 转换、自动标注、评估、训练、发布交付
+
+运行时目录建议始终分开：
+
+- 生成器安装目录：保存 `sinan-generator(.exe)` 和生成器配置
+- 生成器工作区：保存 `workspace.json`、`presets/`、`materials/`、`cache/`、`jobs/`、`logs/`
+- 训练目录：保存 `pyproject.toml`、`.venv/`、`datasets/`、`runs/`、`reports/`
+
+## 仓库结构
+
+下面是源码仓库结构，不是 Windows 训练机的推荐运行目录。训练机目录请看用户指南。
+
+```text
+sinan-captcha/
+  generator/   # Go 生成器工程
+  core/        # Python 训练与数据工程 CLI
+  configs/     # 配置文件
+  materials/   # 背景图、图标和素材 manifest
+  datasets/    # 原始样本、reviewed 数据和 YOLO 数据集
+  reports/     # QA 与评估输出
+  docs/        # 正式文档
+```
+
+## 正式工作流
+
+1. 用 `uvx --from sinan-captcha sinan env setup-train` 创建独立训练目录
+2. 用 `sinan-generator workspace init --workspace <generator-workspace>` 初始化生成器固定工作区
+3. 用 `sinan-generator materials import|fetch --workspace <generator-workspace>` 准备素材
+4. 用 `sinan-generator make-dataset --workspace <generator-workspace>` 直接产出可交给训练 CLI 的 YOLO 数据集目录
+5. 用 `uv run sinan train group1` 或 `uv run sinan train group2` 启动训练
+6. 用 `uv run sinan evaluate` 做 JSONL 对比评估
+
+## 典型命令
+
+```bash
+uvx --from sinan-captcha sinan env setup-train --train-root D:\sinan-captcha-work
+uv run sinan release build --project-dir .
+sinan-generator workspace init --workspace D:\sinan-captcha-generator\workspace
+sinan-generator materials import --workspace D:\sinan-captcha-generator\workspace --from D:\materials-pack
+sinan-generator make-dataset --workspace D:\sinan-captcha-generator\workspace --task group1 --dataset-dir D:\sinan-captcha-work\datasets\group1\firstpass\yolo
+uv run sinan train group1 --dataset-yaml D:\sinan-captcha-work\datasets\group1\firstpass\yolo\dataset.yaml --project D:\sinan-captcha-work\runs\group1
+```
+
+## 文档入口
+
+- [用户指南总览](docs/02-user-guide/user-guide.md)
+- [使用交付物与正式 CLI](docs/02-user-guide/use-build-artifacts.md)
+- [Windows 训练机安装与模型训练完整指南](docs/02-user-guide/from-base-model-to-training-guide.md)
+- [训练完成后的模型使用与测试](docs/02-user-guide/use-and-test-trained-models.md)
+
+## 当前事实
+
+- 生成器模式：`group1 -> click/native`、`group2 -> slide/native`
+- 训练标签：`gold` 真值必须通过一致性校验、重放校验和负样本校验
+- 生成器交付给训练 CLI 的正式接口：YOLO 数据集目录 + `dataset.yaml`
+- 如果生成器命令不显式传 `--workspace`，Windows 默认工作区会落在 `%LOCALAPPDATA%\\SinanGenerator`
+
+这个项目不是 HTTP 服务，也不是单一可执行程序。它是一个围绕本地 CLI、训练数据和模型训练流程组织的工程。

sinan_captcha-0.1.0/README.md

@@ -0,0 +1,72 @@
+# sinan-captcha
+
+`sinan-captcha` 是一个本地训练工程，用来生成和训练两类行为验证码模型：
+
+- `group1`：图形点选
+- `group2`：滑块缺口定位
+
+项目对外只保留两个正式入口：
+
+- `sinan-generator`
+  - Go CLI
+  - 负责固定工作区、素材导入/同步、原始样本生成、批次 QA、YOLO 数据集导出
+- `sinan`
+  - Python CLI
+  - 负责训练目录初始化、素材包构建、JSONL 校验、YOLO 转换、自动标注、评估、训练、发布交付
+
+运行时目录建议始终分开：
+
+- 生成器安装目录：保存 `sinan-generator(.exe)` 和生成器配置
+- 生成器工作区：保存 `workspace.json`、`presets/`、`materials/`、`cache/`、`jobs/`、`logs/`
+- 训练目录：保存 `pyproject.toml`、`.venv/`、`datasets/`、`runs/`、`reports/`
+
+## 仓库结构
+
+下面是源码仓库结构，不是 Windows 训练机的推荐运行目录。训练机目录请看用户指南。
+
+```text
+sinan-captcha/
+  generator/   # Go 生成器工程
+  core/        # Python 训练与数据工程 CLI
+  configs/     # 配置文件
+  materials/   # 背景图、图标和素材 manifest
+  datasets/    # 原始样本、reviewed 数据和 YOLO 数据集
+  reports/     # QA 与评估输出
+  docs/        # 正式文档
+```
+
+## 正式工作流
+
+1. 用 `uvx --from sinan-captcha sinan env setup-train` 创建独立训练目录
+2. 用 `sinan-generator workspace init --workspace <generator-workspace>` 初始化生成器固定工作区
+3. 用 `sinan-generator materials import|fetch --workspace <generator-workspace>` 准备素材
+4. 用 `sinan-generator make-dataset --workspace <generator-workspace>` 直接产出可交给训练 CLI 的 YOLO 数据集目录
+5. 用 `uv run sinan train group1` 或 `uv run sinan train group2` 启动训练
+6. 用 `uv run sinan evaluate` 做 JSONL 对比评估
+
+## 典型命令
+
+```bash
+uvx --from sinan-captcha sinan env setup-train --train-root D:\sinan-captcha-work
+uv run sinan release build --project-dir .
+sinan-generator workspace init --workspace D:\sinan-captcha-generator\workspace
+sinan-generator materials import --workspace D:\sinan-captcha-generator\workspace --from D:\materials-pack
+sinan-generator make-dataset --workspace D:\sinan-captcha-generator\workspace --task group1 --dataset-dir D:\sinan-captcha-work\datasets\group1\firstpass\yolo
+uv run sinan train group1 --dataset-yaml D:\sinan-captcha-work\datasets\group1\firstpass\yolo\dataset.yaml --project D:\sinan-captcha-work\runs\group1
+```
+
+## 文档入口
+
+- [用户指南总览](docs/02-user-guide/user-guide.md)
+- [使用交付物与正式 CLI](docs/02-user-guide/use-build-artifacts.md)
+- [Windows 训练机安装与模型训练完整指南](docs/02-user-guide/from-base-model-to-training-guide.md)
+- [训练完成后的模型使用与测试](docs/02-user-guide/use-and-test-trained-models.md)
+
+## 当前事实
+
+- 生成器模式：`group1 -> click/native`、`group2 -> slide/native`
+- 训练标签：`gold` 真值必须通过一致性校验、重放校验和负样本校验
+- 生成器交付给训练 CLI 的正式接口：YOLO 数据集目录 + `dataset.yaml`
+- 如果生成器命令不显式传 `--workspace`，Windows 默认工作区会落在 `%LOCALAPPDATA%\\SinanGenerator`
+
+这个项目不是 HTTP 服务，也不是单一可执行程序。它是一个围绕本地 CLI、训练数据和模型训练流程组织的工程。

sinan_captcha-0.1.0/core/__init__.py

@@ -0,0 +1,5 @@
+"""Python training and data engineering core package for sinan-captcha."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

sinan_captcha-0.1.0/core/autolabel/__init__.py

@@ -0,0 +1,2 @@
+"""Autolabel entry points for group1 and group2 workflows."""
+

sinan_captcha-0.1.0/core/autolabel/cli.py

@@ -0,0 +1,42 @@
+"""CLI for offline autolabel flows."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from core.autolabel.service import AutolabelRequest, run_autolabel
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run offline autolabel flows.")
+    parser.add_argument("--task", choices=["group1", "group2"], required=True)
+    parser.add_argument("--mode", required=True)
+    parser.add_argument("--input-dir", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--limit", type=int, default=None)
+    parser.add_argument("--jitter-pixels", type=int, default=4)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    result = run_autolabel(
+        AutolabelRequest(
+            task=args.task,
+            mode=args.mode,
+            input_dir=args.input_dir,
+            output_dir=args.output_dir,
+            limit=args.limit,
+            jitter_pixels=args.jitter_pixels,
+        )
+    )
+    print(json.dumps(result.to_dict(), ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sinan_captcha-0.1.0/core/autolabel/service.py

@@ -0,0 +1,191 @@
+"""Offline autolabel flows for reviewed-seed and pseudo-auto datasets."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import hashlib
+from pathlib import Path
+import shutil
+
+from core.common.images import get_image_size
+from core.common.jsonl import read_jsonl, write_jsonl
+from core.dataset.validation import (
+    get_group2_query_image,
+    get_group2_scene_image,
+    get_group2_target,
+    set_group2_target,
+    validate_group1_row,
+    validate_group2_row,
+)
+
+
+@dataclass(frozen=True)
+class AutolabelRequest:
+    task: str
+    mode: str
+    input_dir: Path
+    output_dir: Path
+    limit: int | None = None
+    jitter_pixels: int = 4
+
+
+@dataclass(frozen=True)
+class AutolabelResult:
+    task: str
+    mode: str
+    output_dir: Path
+    labels_path: Path
+    processed_count: int
+
+    def to_dict(self) -> dict[str, object]:
+        payload = asdict(self)
+        payload["output_dir"] = str(self.output_dir)
+        payload["labels_path"] = str(self.labels_path)
+        return payload
+
+
+def run_autolabel(request: AutolabelRequest) -> AutolabelResult:
+    rows = read_jsonl(request.input_dir / "labels.jsonl")
+    selected_rows = _apply_limit(rows, request.limit)
+    output_rows: list[dict[str, object]] = []
+
+    for raw_row in selected_rows:
+        copied_row = dict(raw_row)
+        if request.task == "group1":
+            row = validate_group1_row(copied_row)
+            transformed = _transform_group1_row(row, request)
+        elif request.task == "group2":
+            row = validate_group2_row(copied_row)
+            transformed = _transform_group2_row(row, request)
+        else:
+            raise ValueError(f"unsupported autolabel task: {request.task}")
+
+        if request.task == "group1":
+            _copy_asset(request.input_dir, request.output_dir, Path(str(transformed["query_image"])))
+            _copy_asset(request.input_dir, request.output_dir, Path(str(transformed["scene_image"])))
+        else:
+            _copy_asset(request.input_dir, request.output_dir, Path(get_group2_query_image(transformed)))
+            _copy_asset(request.input_dir, request.output_dir, Path(get_group2_scene_image(transformed)))
+        output_rows.append(transformed)
+
+    labels_path = request.output_dir / "labels.jsonl"
+    write_jsonl(labels_path, output_rows)
+    return AutolabelResult(
+        task=request.task,
+        mode=request.mode,
+        output_dir=request.output_dir,
+        labels_path=labels_path,
+        processed_count=len(output_rows),
+    )
+
+
+def _apply_limit(rows: list[dict[str, object]], limit: int | None) -> list[dict[str, object]]:
+    ordered = sorted(rows, key=lambda row: str(row["sample_id"]))
+    if limit is None or limit >= len(ordered):
+        return ordered
+    return ordered[:limit]
+
+
+def _transform_group1_row(row: dict[str, object], request: AutolabelRequest) -> dict[str, object]:
+    if request.mode == "seed-review":
+        result = dict(row)
+        result["label_source"] = "reviewed"
+        return result
+    if request.mode != "warmup-auto":
+        raise ValueError(f"unsupported group1 autolabel mode: {request.mode}")
+
+    scene_path = request.input_dir / str(row["scene_image"])
+    image_width, image_height = get_image_size(scene_path)
+    result = dict(row)
+    result["targets"] = [
+        _perturb_object(
+            obj,
+            sample_id=str(row["sample_id"]),
+            image_width=image_width,
+            image_height=image_height,
+            jitter_pixels=request.jitter_pixels,
+            salt=f"target:{index}",
+        )
+        for index, obj in enumerate(row["targets"])
+    ]
+    result["distractors"] = [
+        _perturb_object(
+            obj,
+            sample_id=str(row["sample_id"]),
+            image_width=image_width,
+            image_height=image_height,
+            jitter_pixels=request.jitter_pixels,
+            salt=f"distractor:{index}",
+        )
+        for index, obj in enumerate(row["distractors"])
+    ]
+    result["label_source"] = "auto"
+    return result
+
+
+def _transform_group2_row(row: dict[str, object], request: AutolabelRequest) -> dict[str, object]:
+    if request.mode != "rule-auto":
+        raise ValueError(f"unsupported group2 autolabel mode: {request.mode}")
+
+    scene_path = request.input_dir / get_group2_scene_image(row)
+    image_width, image_height = get_image_size(scene_path)
+    result = set_group2_target(
+        row,
+        _perturb_object(
+            get_group2_target(row),
+            sample_id=str(row["sample_id"]),
+            image_width=image_width,
+            image_height=image_height,
+            jitter_pixels=request.jitter_pixels,
+            salt="group2-target",
+        ),
+    )
+    result["label_source"] = "auto"
+    return result
+
+
+def _perturb_object(
+    obj: dict[str, object],
+    *,
+    sample_id: str,
+    image_width: int,
+    image_height: int,
+    jitter_pixels: int,
+    salt: str,
+) -> dict[str, object]:
+    x1, y1, x2, y2 = [int(value) for value in obj["bbox"]]
+    width = max(1, x2 - x1)
+    height = max(1, y2 - y1)
+
+    dx = _stable_offset(sample_id, salt, "dx", jitter_pixels)
+    dy = _stable_offset(sample_id, salt, "dy", jitter_pixels)
+    grow = _stable_offset(sample_id, salt, "grow", max(1, jitter_pixels // 2))
+
+    new_x1 = _clamp(x1 + dx - grow, 0, image_width - 2)
+    new_y1 = _clamp(y1 + dy - grow, 0, image_height - 2)
+    new_x2 = _clamp(x1 + dx + width + grow, new_x1 + 1, image_width)
+    new_y2 = _clamp(y1 + dy + height + grow, new_y1 + 1, image_height)
+
+    updated = dict(obj)
+    updated["bbox"] = [new_x1, new_y1, new_x2, new_y2]
+    updated["center"] = [(new_x1 + new_x2) // 2, (new_y1 + new_y2) // 2]
+    return updated
+
+
+def _stable_offset(sample_id: str, salt: str, axis: str, magnitude: int) -> int:
+    if magnitude <= 0:
+        return 0
+    digest = hashlib.sha256(f"{sample_id}:{salt}:{axis}".encode("utf-8")).digest()
+    span = magnitude * 2 + 1
+    return int(digest[0] % span) - magnitude
+
+
+def _copy_asset(input_dir: Path, output_dir: Path, relative_path: Path) -> None:
+    source = input_dir / relative_path
+    destination = output_dir / relative_path
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, destination)
+
+
+def _clamp(value: int, lower: int, upper: int) -> int:
+    return max(lower, min(value, upper))

sinan_captcha-0.1.0/core/cli.py

@@ -0,0 +1,75 @@
+"""Unified Python CLI for training and data-engineering flows."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+from core.autolabel import cli as autolabel_cli
+from core.convert import cli as convert_cli
+from core.dataset import cli as dataset_cli
+from core.evaluate import cli as evaluate_cli
+from core.materials import cli as materials_cli
+from core.ops import env as env_cli
+from core.ops import setup_train as setup_train_cli
+from core.release import cli as release_cli
+from core.train.group1 import cli as train_group1_cli
+from core.train.group2 import cli as train_group2_cli
+
+CommandHandler = tuple[tuple[str, ...], Callable[[list[str] | None], int]]
+
+COMMANDS: list[CommandHandler] = [
+    (("env", "check"), lambda argv: env_cli.main(argv)),
+    (("env", "setup-train"), lambda argv: setup_train_cli.main(argv)),
+    (("materials", "build"), lambda argv: materials_cli.main(argv)),
+    (("dataset", "validate"), lambda argv: dataset_cli.main(argv)),
+    (("dataset", "build-yolo"), lambda argv: convert_cli.main(argv)),
+    (("autolabel",), lambda argv: autolabel_cli.main(argv)),
+    (("evaluate",), lambda argv: evaluate_cli.main(argv)),
+    (("train", "group1"), lambda argv: train_group1_cli.main(argv)),
+    (("train", "group2"), lambda argv: train_group2_cli.main(argv)),
+    (("release",), lambda argv: release_cli.main(argv)),
+]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in {"-h", "--help", "help"}:
+        print(_usage())
+        return 0
+
+    for tokens, handler in COMMANDS:
+        if args[: len(tokens)] == list(tokens):
+            return handler(args[len(tokens) :])
+
+    print(f"unknown command: {' '.join(args)}", file=sys.stderr)
+    print(_usage(), file=sys.stderr)
+    return 1
+
+
+def _usage() -> str:
+    return "\n".join(
+        [
+            "uv run sinan <command>",
+            "",
+            "Commands:",
+            "  env check                     Check whether the training host is ready.",
+            "  env setup-train               Create a dedicated training root and bootstrap its uv environment.",
+            "  materials build               Build a local offline materials pack.",
+            "  dataset validate              Validate a JSONL dataset file.",
+            "  dataset build-yolo            Convert a labeled batch into a YOLO dataset.",
+            "  autolabel                     Run offline autolabel flows.",
+            "  evaluate                      Evaluate prediction JSONL files against gold data.",
+            "  train group1                  Run group1 YOLO training.",
+            "  train group2                  Run group2 YOLO training.",
+            "  release <subcommand>          Build, publish, or package delivery artifacts.",
+            "",
+            "Examples:",
+            "  uv run sinan env check",
+            "  uv run sinan env setup-train --train-root D:\\sinan-captcha-work",
+            "  uv run sinan materials build --spec configs/materials-pack.toml --output-root materials",
+            "  uv run sinan dataset build-yolo --task group1 --version v1 --source-dir batch --output-dir yolo",
+            "  uv run sinan train group1 --dataset-yaml datasets/group1/v1/yolo/dataset.yaml --project runs/group1",
+            "  uv run sinan release build --project-dir .",
+        ]
+    )

sinan_captcha-0.1.0/core/common/__init__.py

@@ -0,0 +1,2 @@
+"""Shared utilities for the sinan-captcha core package."""
+

sinan_captcha-0.1.0/core/common/images.py

@@ -0,0 +1,76 @@
+"""Image metadata helpers using the Python standard library only."""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+
+def get_image_size(path: Path) -> tuple[int, int]:
+    """Return `(width, height)` for PNG and JPEG images."""
+
+    with path.open("rb") as handle:
+        header = handle.read(24)
+        if len(header) < 24:
+            raise ValueError(f"Image file is too small: {path}")
+
+        if header.startswith(b"\x89PNG\r\n\x1a\n"):
+            width, height = struct.unpack(">II", header[16:24])
+            return width, height
+
+        if header[:2] == b"\xff\xd8":
+            handle.seek(2)
+            return _read_jpeg_size(handle, path)
+
+    raise ValueError(f"Unsupported image format: {path}")
+
+
+def _read_jpeg_size(handle, path: Path) -> tuple[int, int]:
+    while True:
+        marker_prefix = handle.read(1)
+        if not marker_prefix:
+            break
+        if marker_prefix != b"\xff":
+            continue
+
+        marker = handle.read(1)
+        while marker == b"\xff":
+            marker = handle.read(1)
+        if not marker:
+            break
+
+        marker_value = marker[0]
+        if marker_value in {0xD8, 0xD9}:
+            continue
+
+        segment_length_raw = handle.read(2)
+        if len(segment_length_raw) != 2:
+            break
+        segment_length = struct.unpack(">H", segment_length_raw)[0]
+        if segment_length < 2:
+            raise ValueError(f"Invalid JPEG segment length: {path}")
+
+        if marker_value in {
+            0xC0,
+            0xC1,
+            0xC2,
+            0xC3,
+            0xC5,
+            0xC6,
+            0xC7,
+            0xC9,
+            0xCA,
+            0xCB,
+            0xCD,
+            0xCE,
+            0xCF,
+        }:
+            segment = handle.read(segment_length - 2)
+            if len(segment) < 5:
+                break
+            height, width = struct.unpack(">HH", segment[1:5])
+            return width, height
+
+        handle.seek(segment_length - 2, 1)
+
+    raise ValueError(f"Could not determine JPEG size: {path}")

sinan_captcha-0.1.0/core/common/jsonl.py

@@ -0,0 +1,40 @@
+"""Small JSONL helpers used across dataset and report flows."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+JsonMapping = dict[str, Any]
+
+
+def read_jsonl(path: Path) -> list[JsonMapping]:
+    """Read a JSONL file into a list of dictionaries."""
+
+    rows: list[JsonMapping] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line_number, line in enumerate(handle, start=1):
+            raw = line.strip()
+            if not raw:
+                continue
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError as exc:  # pragma: no cover - direct error path
+                message = f"Invalid JSONL at {path}:{line_number}: {exc.msg}"
+                raise ValueError(message) from exc
+            if not isinstance(payload, dict):
+                message = f"Expected object at {path}:{line_number}, got {type(payload).__name__}"
+                raise ValueError(message)
+            rows.append(payload)
+    return rows
+
+
+def write_jsonl(path: Path, rows: list[JsonMapping]) -> None:
+    """Write dictionaries to a UTF-8 JSONL file."""
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False))
+            handle.write("\n")

sinan_captcha-0.1.0/core/common/paths.py

@@ -0,0 +1,29 @@
+"""Repository and work-directory path helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class WorkspacePaths:
+    """Well-known project paths used by scripts and CLIs."""
+
+    repo_root: Path
+    work_root: Path
+    datasets_dir: Path
+    reports_dir: Path
+    dist_dir: Path
+
+    @classmethod
+    def from_roots(cls, repo_root: Path, work_root: Path | None = None) -> "WorkspacePaths":
+        resolved_repo_root = repo_root.resolve()
+        resolved_work_root = (work_root or resolved_repo_root).resolve()
+        return cls(
+            repo_root=resolved_repo_root,
+            work_root=resolved_work_root,
+            datasets_dir=resolved_work_root / "datasets",
+            reports_dir=resolved_work_root / "reports",
+            dist_dir=resolved_repo_root / "dist",
+        )

sinan_captcha-0.1.0/core/convert/__init__.py

@@ -0,0 +1,2 @@
+"""Dataset conversion entry points."""
+

sinan_captcha-0.1.0/core/convert/cli.py

@@ -0,0 +1,37 @@
+"""CLI for JSONL to YOLO conversion flows."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from core.convert.service import ConversionRequest, build_yolo_dataset
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Convert JSONL source-of-truth files into YOLO datasets.")
+    parser.add_argument("--task", choices=["group1", "group2"], required=True)
+    parser.add_argument("--version", required=True)
+    parser.add_argument("--source-dir", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    build_yolo_dataset(
+        ConversionRequest(
+            task=args.task,
+            version=args.version,
+            source_dir=args.source_dir,
+            output_dir=args.output_dir,
+        )
+    )
+    print(f"built YOLO dataset at {args.output_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())