starforge-core 0.1.6__tar.gz

starforge_core-0.1.6/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.python-version
+.pytest_cache/
+.ruff_cache/
+
+# 前端
+web/node_modules/
+web/dist/
+
+# 本地数据库 / 凭据 / 台账
+.forge/
+*.db
+
+# 密钥 / 本地配置
+.env
+.env.*
+!.env.example
+docker-compose.override.yml
+*.key
+secrets.*
+
+# 系统 / 编辑器
+.DS_Store
+.idea/
+.vscode/
+*.swp
+SwanLab/
+RL/

starforge_core-0.1.6/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: starforge-core
+Version: 0.1.6
+Summary: StarForge 平台契约内核：Console/CLI 共享 JobSpec 与 recipe，作业侧由 Job Capsule PEX 携带。
+Requires-Python: >=3.10
+Requires-Dist: packaging>=24
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'

starforge_core-0.1.6/gitlab-ci.example.yml

@@ -0,0 +1,19 @@
+core:test-and-build:
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+  script:
+    - uv run --project core --extra dev pytest -q core/tests
+    - uv run --project core --extra dev ruff check core
+    - bash core/scripts/build_and_check.sh core/dist
+  artifacts:
+    paths:
+      - core/dist/
+
+core:publish:
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+  needs: [core:test-and-build]
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^core-v/'
+  script:
+    - test -n "$UV_PUBLISH_USERNAME"
+    - test -n "$UV_PUBLISH_PASSWORD"
+    - uv publish --publish-url "$NEXUS_PYPI_PUBLISH_URL" core/dist/starforge_core-*

starforge_core-0.1.6/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "starforge-core"
+version = "0.1.6"
+description = "StarForge 平台契约内核：Console/CLI 共享 JobSpec 与 recipe，作业侧由 Job Capsule PEX 携带。"
+requires-python = ">=3.10"
+# packaging 是 recipe runtime.requires 的强校验器；缺失时必须在启动阶段失败，
+# 不能悄悄跳过兼容检查。上报仍走标准库 urllib，不引 requests。
+dependencies = ["packaging>=24", "pyyaml>=6"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5"]
+
+[project.scripts]
+# 集群侧作业入口：容器 CMD 直接调它，不再需要上传包里的 shell 脚本。
+forge-launch = "starforge_core.launcher:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["starforge_core"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B"]
+ignore = ["E501", "B008"]

starforge_core-0.1.6/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+testpaths = tests
+pythonpath = .

starforge_core-0.1.6/scripts/build_and_check.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CORE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT_DIR="${1:-${CORE_ROOT}/dist}"
+
+VERSION="$(python3 - "${CORE_ROOT}/pyproject.toml" <<'PY'
+import re, sys
+text = open(sys.argv[1], encoding="utf-8").read()
+match = re.search(r'(?m)^version\s*=\s*"([^"]+)"', text)
+if not match:
+    raise SystemExit("core/pyproject.toml 里没有 version")
+print(match.group(1))
+PY
+)"
+
+mkdir -p "${OUT_DIR}"
+uv build "${CORE_ROOT}" --out-dir "${OUT_DIR}"
+
+WHEEL="$(find "${OUT_DIR}" -maxdepth 1 -name "starforge_core-${VERSION}-*.whl" -print -quit)"
+if [[ -z "${WHEEL}" ]]; then
+  echo "starforge-core ${VERSION} wheel 未生成" >&2
+  exit 1
+fi
+
+python3 - "${WHEEL}" <<'PY'
+import sys
+import zipfile
+
+with zipfile.ZipFile(sys.argv[1]) as archive:
+    names = set(archive.namelist())
+
+required = {
+    "starforge_core/recipes/catalog/nemo-rl/grpo/template/config.yaml",
+    "starforge_core/recipes/catalog/verl/grpo/recipe.yaml",
+    "starforge_core/recipes/catalog/trl/grpo/recipe.yaml",
+    "starforge_core/recipes/catalog/custom/custom/recipe.yaml",
+}
+missing = sorted(required - names)
+if missing:
+    raise SystemExit("core wheel 缺少 package data: " + ", ".join(missing))
+PY
+echo "core wheel verified: ${WHEEL}"

starforge_core-0.1.6/starforge_core/__init__.py

@@ -0,0 +1,80 @@
+"""starforge-core —— 平台与集群之间的契约内核。
+
+谁在用
+──────────────────────────────────────────────────────────────────────────────
+  console（控制面）  校验 JobSpec、按 recipe 目录做准入、装配作业
+  sf CLI（客户端）   构建 JobSpec、本地按 recipe schema 预校验
+  训练镜像（集群侧） launcher 读 spec 决定怎么跑；reporter 回传平台事实
+
+为什么独立成包
+──────────────────────────────────────────────────────────────────────────────
+三方都只依赖这一个包，任何一方都不依赖另一方。若契约住在某个客户端包里，
+控制面就会反向依赖自己的客户端，客户端发版就可能牵动平台。
+
+契约的**所有权**归平台（源码在 console 仓），因为「支持哪些后训练方法、
+作业规格长什么样」是平台的决定，不是某个客户端的决定。
+
+依赖极简（仅 pyyaml，上报走标准库 urllib）：本包要能在任何训练镜像里 import，
+少一个依赖就少一处「镜像里恰好没装」的失败点。
+"""
+from __future__ import annotations
+
+__version__ = "0.1.6"
+
+from .contract import (
+    API_VERSION,
+    KIND_TRAINING,
+    KNOWN_KEYS,
+    SPEC_FILE_PATH,
+    ArtifactRef,
+    DistributedTopology,
+    IngestBinding,
+    JobSpec,
+    JobSpecBody,
+    LifecycleSpec,
+    Metadata,
+    ModelSpec,
+    PlatformBinding,
+    Provenance,
+    RecipeRef,
+    ResourcePool,
+    ResourceSpec,
+    SourceSpec,
+    SpecError,
+    compile_distributed_topology,
+    compile_pool_topologies,
+    spec_to_env,
+)
+from .recipes import Recipe, all_recipes, get_recipe, recipe_names
+from .reporter import Reporter
+
+__all__ = [
+    "API_VERSION",
+    "ArtifactRef",
+    "DistributedTopology",
+    "IngestBinding",
+    "JobSpec",
+    "JobSpecBody",
+    "KIND_TRAINING",
+    "KNOWN_KEYS",
+    "LifecycleSpec",
+    "Metadata",
+    "ModelSpec",
+    "PlatformBinding",
+    "Provenance",
+    "Recipe",
+    "RecipeRef",
+    "ResourcePool",
+    "ResourceSpec",
+    "Reporter",
+    "SPEC_FILE_PATH",
+    "SourceSpec",
+    "SpecError",
+    "compile_distributed_topology",
+    "compile_pool_topologies",
+    "all_recipes",
+    "get_recipe",
+    "recipe_names",
+    "spec_to_env",
+    "__version__",
+]

starforge_core-0.1.6/starforge_core/artifacts.py

@@ -0,0 +1,140 @@
+"""Recipe-owned artifact discovery and ``forge/artifacts/v1`` manifests."""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from starforge_core.recipes import ArtifactContract
+from starforge_core.reporter import Reporter
+
+MANIFEST_NAME = "artifacts.json"
+_STEP_RE = re.compile(r"(?:^|/)(?:global_)?step_(\d+)(?:/|$)")
+
+
+def _contained(root: Path, path: Path) -> Path:
+    resolved = path.resolve(strict=True)
+    if not resolved.is_relative_to(root):
+        raise ValueError(f"artifact glob 越过 FORGE_OUT_DIR: {path} -> {resolved}")
+    return resolved
+
+
+def _size_bytes(root: Path, path: Path) -> int:
+    if path.is_file():
+        return path.stat().st_size
+    total = 0
+    for item in path.rglob("*"):
+        resolved = _contained(root, item)
+        if resolved.is_file():
+            total += resolved.stat().st_size
+    return total
+
+
+def _step(relative: str) -> int | None:
+    match = _STEP_RE.search(relative)
+    return int(match.group(1)) if match else None
+
+
+def _materialized_format(declared: str, path: Path) -> str:
+    if declared != "nemo-checkpoint":
+        return declared
+    weights = path / "policy" / "weights"
+    dcp = (weights / ".metadata").is_file()
+    megatron = [item for item in weights.glob("iter_*") if item.is_dir()] if weights.is_dir() else []
+    if dcp and not megatron:
+        return "nemo-dcp"
+    if len(megatron) == 1 and not dcp:
+        return "nemo-megatron"
+    raise ValueError(
+        f"NeMo checkpoint format 无法唯一确定: {path} "
+        f"(dcp_metadata={dcp}, megatron_iterations={len(megatron)})"
+    )
+
+
+def _sort_key(item: dict[str, Any]) -> tuple[int, int, str]:
+    return (
+        0 if item["kind"] == "checkpoint" else 1,
+        item.get("step") if item.get("step") is not None else -1,
+        item["path"],
+    )
+
+
+def build_manifest(
+    output_root: Path,
+    *,
+    run_id: str,
+    framework: str,
+    recipe: str,
+    contract: ArtifactContract,
+) -> dict[str, Any]:
+    """Expand only declared globs and reject every realpath escape."""
+    root = output_root.expanduser().resolve(strict=True)
+    if contract.version != "forge/artifacts/v1":
+        raise ValueError(f"不支持的 artifact manifest 版本: {contract.version!r}")
+    groups = (
+        ("checkpoint", contract.checkpoints),
+        ("log", contract.logs),
+        ("hf_export", contract.exports),
+        ("eval_report", contract.evaluations),
+    )
+    artifacts: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for kind, patterns in groups:
+        artifact_format = contract.formats.get(kind, "").strip()
+        if not artifact_format:
+            raise ValueError(f"artifact kind {kind!r} 缺少显式 format")
+        for pattern in patterns:
+            for match in root.glob(pattern):
+                resolved = _contained(root, match)
+                relative = match.relative_to(root).as_posix()
+                identity = (kind, relative)
+                if identity in seen:
+                    continue
+                seen.add(identity)
+                item: dict[str, Any] = {
+                    "kind": kind,
+                    "path": relative,
+                    "format": _materialized_format(artifact_format, resolved),
+                    "size_bytes": _size_bytes(root, resolved),
+                }
+                if (step := _step(relative)) is not None:
+                    item["step"] = step
+                artifacts.append(item)
+    artifacts.sort(key=_sort_key)
+    return {
+        "apiVersion": "forge/artifacts/v1",
+        "run_id": run_id,
+        "framework": framework,
+        "recipe": recipe,
+        "artifacts": artifacts,
+    }
+
+
+def write_manifest(output_root: Path, manifest: dict[str, Any]) -> Path:
+    root = output_root.expanduser().resolve(strict=True)
+    path = root / MANIFEST_NAME
+    path.write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return path
+
+
+def publish_manifest(
+    manifest: dict[str, Any],
+    *,
+    output_root: Path,
+    reporter: Reporter | None,
+) -> None:
+    if reporter is None:
+        return
+    root = output_root.expanduser().resolve(strict=True)
+    for item in manifest.get("artifacts", ()):
+        reporter.artifact(
+            item["kind"],
+            str(_contained(root, root / item["path"])),
+            step=item.get("step"),
+            size_bytes=item.get("size_bytes"),
+            format=item["format"],
+        )

starforge_core-0.1.6/starforge_core/benchmarks/__init__.py

@@ -0,0 +1,20 @@
+"""标准基准评测的 runner 抽象（lm-eval / evalscope 双后端）。"""
+from __future__ import annotations
+
+from .runners import (
+    BenchmarkRunner,
+    BenchmarkScore,
+    EvalscopeRunner,
+    LmEvalRunner,
+    RunnerError,
+    get_runner,
+)
+
+__all__ = [
+    "BenchmarkRunner",
+    "BenchmarkScore",
+    "EvalscopeRunner",
+    "LmEvalRunner",
+    "RunnerError",
+    "get_runner",
+]

starforge_core-0.1.6/starforge_core/benchmarks/runners.py

@@ -0,0 +1,163 @@
+"""BenchmarkRunner 协议与两个一等实现（lm-eval / evalscope）。
+
+设计：
+  - runner = 「构造评测命令 + 解析分数产物」的适配器；进程执行、超时、
+    产物落盘与上报由 lifecycle.benchmark_eval 统一负责。
+  - 分数统一归一成 BenchmarkScore(benchmark, metric, value)——console 的
+    benchmark_scores 表与看板端点按这三元组聚合，不关心后端差异。
+  - 解析失败显式抛 RunnerError（评测跑完但拿不到分数 = 作业失败，
+    不允许静默产出空报告）。
+"""
+from __future__ import annotations
+
+import json
+import shlex
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+class RunnerError(RuntimeError):
+    """评测 runner 命令构造/产物解析失败。"""
+
+
+@dataclass(frozen=True)
+class BenchmarkScore:
+    benchmark: str
+    metric: str
+    value: float
+
+    def to_dict(self) -> dict:
+        return {"benchmark": self.benchmark, "metric": self.metric, "value": self.value}
+
+
+class BenchmarkRunner(Protocol):
+    name: str
+
+    def build_argv(
+        self, *, model: str, suites: list[str], output_dir: Path,
+        batch_size: str, limit: int | None, extra_args: str,
+    ) -> list[str]: ...
+
+    def parse_scores(self, output_dir: Path) -> list[BenchmarkScore]: ...
+
+
+def _finite(value) -> float | None:
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return None
+    return v if v == v and abs(v) != float("inf") else None
+
+
+class LmEvalRunner:
+    """EleutherAI lm-evaluation-harness（学术标准基准的事实标准）。"""
+
+    name = "lm-eval"
+
+    def build_argv(
+        self, *, model: str, suites: list[str], output_dir: Path,
+        batch_size: str, limit: int | None, extra_args: str,
+    ) -> list[str]:
+        argv = [
+            sys.executable, "-m", "lm_eval",
+            "--model", "hf",
+            "--model_args", f"pretrained={model}",
+            "--tasks", ",".join(suites),
+            "--batch_size", batch_size or "auto",
+            "--output_path", str(output_dir),
+            "--log_samples",
+        ]
+        if limit:
+            argv += ["--limit", str(limit)]
+        if extra_args:
+            argv += shlex.split(extra_args)
+        return argv
+
+    def parse_scores(self, output_dir: Path) -> list[BenchmarkScore]:
+        """解析 lm-eval 的 results*.json（新版本落在 output_path 下的模型子目录）。"""
+        candidates = sorted(output_dir.rglob("results*.json"))
+        if not candidates:
+            raise RunnerError(f"lm-eval 未产出 results*.json（查 {output_dir}）")
+        data = json.loads(candidates[-1].read_text(encoding="utf-8"))
+        results = data.get("results")
+        if not isinstance(results, dict) or not results:
+            raise RunnerError("lm-eval results 段为空")
+        scores: list[BenchmarkScore] = []
+        for task, metrics in results.items():
+            if not isinstance(metrics, dict):
+                continue
+            for key, raw in metrics.items():
+                # 键形如 "acc,none" / "exact_match,strict-match"；跳过 stderr 与别名字段
+                metric = str(key).split(",", 1)[0]
+                if metric in ("alias",) or metric.endswith("_stderr"):
+                    continue
+                if (value := _finite(raw)) is not None:
+                    scores.append(BenchmarkScore(str(task), metric, value))
+        if not scores:
+            raise RunnerError("lm-eval results 未解析出任何数值指标")
+        return scores
+
+
+class EvalscopeRunner:
+    """ModelScope evalscope（中文基准如 C-Eval/CMMLU 覆盖更好）。"""
+
+    name = "evalscope"
+
+    def build_argv(
+        self, *, model: str, suites: list[str], output_dir: Path,
+        batch_size: str, limit: int | None, extra_args: str,
+    ) -> list[str]:
+        argv = [
+            sys.executable, "-m", "evalscope.cli.cli", "eval",
+            "--model", model,
+            "--datasets", *suites,
+            "--work-dir", str(output_dir),
+        ]
+        if limit:
+            argv += ["--limit", str(limit)]
+        if extra_args:
+            argv += shlex.split(extra_args)
+        return argv
+
+    def parse_scores(self, output_dir: Path) -> list[BenchmarkScore]:
+        """解析 evalscope 的 reports/**/*.json（每数据集一份报告）。"""
+        reports = [
+            p for p in sorted(output_dir.rglob("*.json"))
+            if "reports" in p.parts
+        ]
+        if not reports:
+            raise RunnerError(f"evalscope 未产出 reports/**/*.json（查 {output_dir}）")
+        scores: list[BenchmarkScore] = []
+        for path in reports:
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except ValueError:
+                continue
+            if not isinstance(data, dict):
+                continue
+            dataset = str(data.get("dataset_name") or data.get("name") or path.stem)
+            # 首选 metrics 数组（新版报告）；回退顶层 score 字段。
+            metrics = data.get("metrics")
+            if isinstance(metrics, list):
+                for m in metrics:
+                    if isinstance(m, dict) and (value := _finite(m.get("score"))) is not None:
+                        scores.append(BenchmarkScore(dataset, str(m.get("name") or "score"), value))
+            elif (value := _finite(data.get("score"))) is not None:
+                scores.append(BenchmarkScore(dataset, "score", value))
+        if not scores:
+            raise RunnerError("evalscope 报告未解析出任何数值指标")
+        return scores
+
+
+_RUNNERS = {r.name: r for r in (LmEvalRunner(), EvalscopeRunner())}
+
+
+def get_runner(name: str) -> BenchmarkRunner:
+    try:
+        return _RUNNERS[name]
+    except KeyError as exc:
+        raise RunnerError(
+            f"未知评测 runner {name!r}；可用: {', '.join(sorted(_RUNNERS))}"
+        ) from exc