agent-tune-kit 2.1.0__tar.gz → 2.2.0__tar.gz

{agent_tune_kit-2.1.0 → agent_tune_kit-2.2.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Local Codex plugin for iterative Agent tuning with guided Skills, reusable runner templates, versioned results, and static validation.",
   "author": {
     "name": "hustyichi",

{agent_tune_kit-2.1.0 → agent_tune_kit-2.2.0}/.gitignore

@@ -36,4 +36,5 @@ node_modules/
 .pnpm-store/
 
 # Agent tune kit generated outputs
-.atk/
+.atk/
+!templates/.atk/

{agent_tune_kit-2.1.0 → agent_tune_kit-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.1.0
+Version: 2.2.0
 Summary: Local Codex plugin for iterative Agent tuning with guided Skills, reusable runner templates, versioned results, and static validation.
 Project-URL: Homepage, https://github.com/hustyichi/agent-tune-kit
 Project-URL: Repository, https://github.com/hustyichi/agent-tune-kit
@@ -14,6 +14,12 @@ Description-Content-Type: text/markdown
 
 # Agent Tune Kit
 
+Ground-truth reviews, judge calibration and assessment provenance are documented in
+[the trust contract](docs/truth-and-assessment.md). Existing datasets remain readable, not automatically certified.
+`atk dataset inspect/update` supports content-bound confirmations; `atk results calibrate` checks reviewed outputs
+without executing the Agent or allocating an evaluation version. Rejudgments preserve history and comparisons expose
+changes to their criteria and judge.
+
 English | [简体中文](README.md)
 
 [![PyPI](https://img.shields.io/pypi/v/agent-tune-kit.svg)](https://pypi.org/project/agent-tune-kit/)
@@ -46,13 +52,7 @@ This turns Agent tuning from one-off subjective trial and error into an engineer
 
 ## Install
 
-One-command install:
-
-```sh
-uvx --from agent-tune-kit atk install
-```
-
-To keep the `atk` command available:
+Install the ATK CLI, then install its bundled Skills:
 
 ```sh
 uv tool install agent-tune-kit
@@ -192,3 +192,46 @@ Common output files:
 - `$atk-report`: generate analysis and cross-loop validation.
 - `$atk-visualize-failures`: generate the failure review HTML page.
 - `$atk-optimize`: tune the Agent based on the report.
+
+Legacy one-shot installation remains available: `uvx --from agent-tune-kit atk install`. Skills now require the persistent `atk` command on PATH.
+
+## Shared CLI capabilities
+
+Install the ATK CLI first, then run `atk install` to install its bundled Skills. Fixed operations are maintained in the Python package; Skills retain semantic diagnosis, reporting and Agent optimization.
+
+```sh
+atk dataset prepare --source data/eval.csv
+atk dataset inspect --direct --json
+atk dataset update --direct --field expected --updates-path updates.csv
+atk eval --check --json
+atk eval --limit 5 --concurrency 2
+atk results inspect --json
+atk results run-rule
+atk results apply-judgments --judgments-path judgments.csv --source-results .atk/results/v1/eval_results.csv
+atk results compare --ids 1 2 --json
+atk visualize dataset --no-open
+atk visualize failures --no-open
+```
+
+These commands run from the Agent project. New project adapters delegate to the shared engine; legacy full runners require migration before writing alongside new evidence Runs. Dataset fields, IDs, result paths, unknown verdicts, logs and offline review pages retain their contracts. Use `--help` on each command for its options.
+
+
+## 本地执行证据 / Local execution evidence
+
+V2 adapters declare `ATK_ADAPTER_VERSION = 2` and `EVIDENCE.retain(role, value)`.
+Each execution saves independent input/output, context, structured events and artifacts beneath
+`.atk/results/vN/executions/<id>/`; shared Cases map multiple selected samples to one directory.
+Retention runs before persistence. Existing V1 adapters remain explicit; no historical migration is automatic.
+
+```sh
+atk results inspect --json
+atk results evidence --version v1 --atk-id 1 --json
+atk results evidence --execution-dir ./copied-execution --json
+atk results import-evidence --source ./native-run --adapter ./importer.py --json
+```
+
+`inspect` separates latest Run from the evaluation target. Evidence-only imports do not displace the latter.
+Diagnosis and reports bind `--version`; changed evidence invalidates dependent judgments. Import adapters are
+trusted Python code, not a sandbox. No Agent call, remote fetch, automatic cleanup or post-seal supplementation
+is performed. Declared capture coverage is distinct from successful persistence and business verdicts.
+See [execution evidence plan](docs/execution-evidence-and-tracing-plan.md) for interfaces, source limitations, recovery and validation.

{agent_tune_kit-2.1.0 → agent_tune_kit-2.2.0}/README.en.md

@@ -1,5 +1,11 @@
 # Agent Tune Kit
 
+Ground-truth reviews, judge calibration and assessment provenance are documented in
+[the trust contract](docs/truth-and-assessment.md). Existing datasets remain readable, not automatically certified.
+`atk dataset inspect/update` supports content-bound confirmations; `atk results calibrate` checks reviewed outputs
+without executing the Agent or allocating an evaluation version. Rejudgments preserve history and comparisons expose
+changes to their criteria and judge.
+
 English | [简体中文](README.md)
 
 [![PyPI](https://img.shields.io/pypi/v/agent-tune-kit.svg)](https://pypi.org/project/agent-tune-kit/)
@@ -32,13 +38,7 @@ This turns Agent tuning from one-off subjective trial and error into an engineer
 
 ## Install
 
-One-command install:
-
-```sh
-uvx --from agent-tune-kit atk install
-```
-
-To keep the `atk` command available:
+Install the ATK CLI, then install its bundled Skills:
 
 ```sh
 uv tool install agent-tune-kit
@@ -178,3 +178,46 @@ Common output files:
 - `$atk-report`: generate analysis and cross-loop validation.
 - `$atk-visualize-failures`: generate the failure review HTML page.
 - `$atk-optimize`: tune the Agent based on the report.
+
+Legacy one-shot installation remains available: `uvx --from agent-tune-kit atk install`. Skills now require the persistent `atk` command on PATH.
+
+## Shared CLI capabilities
+
+Install the ATK CLI first, then run `atk install` to install its bundled Skills. Fixed operations are maintained in the Python package; Skills retain semantic diagnosis, reporting and Agent optimization.
+
+```sh
+atk dataset prepare --source data/eval.csv
+atk dataset inspect --direct --json
+atk dataset update --direct --field expected --updates-path updates.csv
+atk eval --check --json
+atk eval --limit 5 --concurrency 2
+atk results inspect --json
+atk results run-rule
+atk results apply-judgments --judgments-path judgments.csv --source-results .atk/results/v1/eval_results.csv
+atk results compare --ids 1 2 --json
+atk visualize dataset --no-open
+atk visualize failures --no-open
+```
+
+These commands run from the Agent project. New project adapters delegate to the shared engine; legacy full runners require migration before writing alongside new evidence Runs. Dataset fields, IDs, result paths, unknown verdicts, logs and offline review pages retain their contracts. Use `--help` on each command for its options.
+
+
+## 本地执行证据 / Local execution evidence
+
+V2 adapters declare `ATK_ADAPTER_VERSION = 2` and `EVIDENCE.retain(role, value)`.
+Each execution saves independent input/output, context, structured events and artifacts beneath
+`.atk/results/vN/executions/<id>/`; shared Cases map multiple selected samples to one directory.
+Retention runs before persistence. Existing V1 adapters remain explicit; no historical migration is automatic.
+
+```sh
+atk results inspect --json
+atk results evidence --version v1 --atk-id 1 --json
+atk results evidence --execution-dir ./copied-execution --json
+atk results import-evidence --source ./native-run --adapter ./importer.py --json
+```
+
+`inspect` separates latest Run from the evaluation target. Evidence-only imports do not displace the latter.
+Diagnosis and reports bind `--version`; changed evidence invalidates dependent judgments. Import adapters are
+trusted Python code, not a sandbox. No Agent call, remote fetch, automatic cleanup or post-seal supplementation
+is performed. Declared capture coverage is distinct from successful persistence and business verdicts.
+See [execution evidence plan](docs/execution-evidence-and-tracing-plan.md) for interfaces, source limitations, recovery and validation.

{agent_tune_kit-2.1.0 → agent_tune_kit-2.2.0}/README.md

@@ -1,5 +1,10 @@
 # Agent Tune Kit
 
+真值复核、裁判校准和判定追溯见[可信度契约](docs/truth-and-assessment.md)：数据集可按答案字段记录来源和
+有效确认，输入/答案/标准变化会使确认过期；`atk dataset update --review-path dataset_review.csv` 可只导入
+确认而不改答案。`atk results calibrate` 用已复核输出检查裁判，不调用 Agent 或创建评测轮次。
+判定可绑定标准与裁判快照，重判保存历史，比较显式列出可比性差异。旧数据可读，但不自动标为已确认。
+
 简体中文 | [English](README.en.md)
 
 [![PyPI](https://img.shields.io/pypi/v/agent-tune-kit.svg)](https://pypi.org/project/agent-tune-kit/)
@@ -32,13 +37,7 @@ Agent Tune Kit 的价值不只是“跑一次测试”，而是把 Agent 调优
 
 ## 安装
 
-一键运行：
-
-```sh
-uvx --from agent-tune-kit atk install
-```
-
-如果希望长期保留 `atk` 命令，可以改用：
+先安装 ATK CLI，再安装配套 Skills：
 
 ```sh
 uv tool install agent-tune-kit
@@ -182,3 +181,47 @@ ATK 可选读取本地私有的 `.atk/context.md`，用于保存用户沟通后
 ## 能力评估
 
 - [Ground truth 与评分方案支持评估（2026-10-25）](docs/ground-truth-and-grading-assessment-2026-10-25.md)：基于当前源码与 44 项相关测试，梳理数据准备、人工校准和判定支持，区分小规模调优可用性与可信评分体系的缺口；未重新验收业务调优效果。
+- [执行项现场与调用轨迹改造实现方案（2026-10-26）](docs/execution-evidence-and-tracing-plan.md)：明确每项独立现场、V2 托管采集及外部 runner 本地证据导入，结合 Magic 双 Case 实践补齐来源身份、文件变更与验收；首版不做封存后补采，按 P0–P5 实施，详见方案中的验收状态。
+
+兼容一次性安装命令 `uvx --from agent-tune-kit atk install`；日常使用 Skill 需要 PATH 中持续可用的 `atk` 命令。
+
+## 统一 CLI 能力
+
+固定操作由 Python 包维护，Skill 继续负责语义诊断、报告分析和 Agent 优化。可在目标 Agent 项目中使用以下命令：
+
+```sh
+atk dataset prepare --source data/eval.csv
+atk dataset inspect --direct --json
+atk dataset update --direct --field expected --updates-path updates.csv
+atk eval --check --json
+atk eval --limit 5 --concurrency 2
+atk results inspect --json
+atk results run-rule
+atk results apply-judgments --judgments-path judgments.csv --source-results .atk/results/v1/eval_results.csv
+atk results compare --ids 1 2 --json
+atk visualize dataset --no-open
+atk visualize failures --no-open
+```
+
+新生成的项目适配文件使用统一执行引擎，旧完整 runner 与新证据现场共存时需先满足写入保护，否则启动前提示迁移。数据字段、ID、结果目录、未判定状态、日志和离线浏览页遵循原有约定。各命令参数见对应 `--help`。
+
+
+## 本地执行证据 / Local execution evidence
+
+V2 adapters declare `ATK_ADAPTER_VERSION = 2` and `EVIDENCE.retain(role, value)`.
+Each execution saves independent input/output, context, structured events and artifacts beneath
+`.atk/results/vN/executions/<id>/`; shared Cases map multiple selected samples to one directory.
+Retention runs before persistence. Existing V1 adapters remain explicit; no historical migration is automatic.
+
+```sh
+atk results inspect --json
+atk results evidence --version v1 --atk-id 1 --json
+atk results evidence --execution-dir ./copied-execution --json
+atk results import-evidence --source ./native-run --adapter ./importer.py --json
+```
+
+`inspect` separates latest Run from the evaluation target. Evidence-only imports do not displace the latter.
+Diagnosis and reports bind `--version`; changed evidence invalidates dependent judgments. Import adapters are
+trusted Python code, not a sandbox. No Agent call, remote fetch, automatic cleanup or post-seal supplementation
+is performed. Declared capture coverage is distinct from successful persistence and business verdicts.
+See [execution evidence plan](docs/execution-evidence-and-tracing-plan.md) for interfaces, source limitations, recovery and validation.

{agent_tune_kit-2.1.0/src → agent_tune_kit-2.2.0}/agent_tune_kit/__init__.py

@@ -1,3 +1,3 @@
 """Agent Tune Kit package."""
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"

agent_tune_kit-2.2.0/agent_tune_kit/cli/__init__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+__all__ = ["main"]

agent_tune_kit-2.2.0/agent_tune_kit/cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+raise SystemExit(main())

agent_tune_kit-2.2.0/agent_tune_kit/cli/dataset.py

@@ -0,0 +1,81 @@
+from agent_tune_kit import datasets
+from agent_tune_kit.datasets import updates
+from agent_tune_kit.workspace import DATASET_PATH
+
+
+def add_options(parser):
+    parser.add_argument("--dataset-path", default=str(DATASET_PATH))
+    parser.add_argument("--field", default="ground_truth")
+    parser.add_argument("--input-fields", nargs="+")
+    parser.add_argument("--home-dir")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--review-path")
+    mode.add_argument("--direct", action="store_true")
+    parser.add_argument("--json", action="store_true")
+
+
+def register(subparsers):
+    commands = subparsers.add_parser("dataset", help="prepare, inspect and update evaluation data").add_subparsers(
+        dest="action", required=True
+    )
+    prepare = commands.add_parser("prepare")
+    prepare.add_argument("--source", required=True)
+    prepare.add_argument("--dataset-path", default=str(DATASET_PATH))
+    mode = prepare.add_mutually_exclusive_group()
+    mode.add_argument("--append", action="store_true")
+    mode.add_argument("--overwrite", action="store_true")
+    prepare.add_argument("--json", action="store_true")
+    add_options(commands.add_parser("inspect"))
+    update = commands.add_parser("update")
+    add_options(update)
+    update.add_argument("--updates-path")
+
+
+def execute(args):
+    if args.action == "prepare":
+        return datasets.prepare_dataset(args.source, args.dataset_path, append=args.append, overwrite=args.overwrite)
+    options = dict(
+        dataset_path=args.dataset_path,
+        direct=args.direct,
+        review_path=args.review_path,
+        field=args.field,
+        home_dir=args.home_dir,
+        input_fields=args.input_fields,
+    )
+    if args.action == "inspect":
+        return datasets.inspect_dataset(**options)
+    return datasets.update_dataset(args.updates_path, **options)
+
+
+def legacy_main(argv=None):
+    import argparse
+    import json
+    import sys
+
+    parser = argparse.ArgumentParser()
+    add_options(parser)
+    parser.add_argument("--updates-path")
+    parser.add_argument("--dump-context", action="store_true")
+    args = parser.parse_args(argv)
+    options = dict(
+        dataset_path=args.dataset_path,
+        direct=args.direct,
+        review_path=args.review_path,
+        field=args.field,
+        home_dir=args.home_dir,
+        input_fields=args.input_fields,
+    )
+    try:
+        if args.dump_context or not args.updates_path:
+            print(json.dumps(datasets.inspect_dataset(**options), ensure_ascii=False, indent=2))
+        if args.updates_path:
+            from .output import emit
+
+            emit(datasets.update_dataset(args.updates_path, **options))
+        return 0
+    except updates.UserActionRequired as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"Unexpected error: {exc}", file=sys.stderr)
+        return 1

agent_tune_kit-2.2.0/agent_tune_kit/cli/evaluation.py

@@ -0,0 +1,22 @@
+from agent_tune_kit.execution import run_evaluation
+
+
+def register(subparsers):
+    parser = subparsers.add_parser("eval", help="run the project Agent with the shared engine")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--limit", type=int)
+    parser.add_argument("--offset", type=int, default=0)
+    parser.add_argument("--concurrency", type=int, default=1)
+    parser.add_argument("--only-failures", action="store_true")
+    parser.add_argument("--no-progress", action="store_true")
+    parser.add_argument("--python")
+    parser.add_argument("--json", action="store_true")
+
+
+def execute(args):
+    return run_evaluation(
+        **{
+            key: getattr(args, key)
+            for key in ["check", "limit", "offset", "concurrency", "only_failures", "no_progress", "python"]
+        }
+    )

agent_tune_kit-2.2.0/agent_tune_kit/cli/main.py

@@ -0,0 +1,55 @@
+"""Public command dispatch; business behavior lives in domain packages."""
+
+import argparse
+import sys
+
+from agent_tune_kit import installer
+from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.execution.runtime import ExecutionFailed
+
+from . import dataset, evaluation, results, visualize
+from .output import emit
+
+HANDLERS = {"dataset": dataset, "eval": evaluation, "results": results, "visualize": visualize}
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "_legacy":
+        if argv[1] == "atk-dataset":
+            return dataset.legacy_main(argv[2:])
+        return visualize.legacy_main("dataset" if argv[1] == "atk-visualize-dataset" else "failures", argv[2:])
+    if not argv or argv[0] not in HANDLERS:
+        if argv and argv[0] in ["-h", "--help"]:
+            parser = argparse.ArgumentParser(description="Register Agent Tune Kit and run shared project capabilities")
+            subparsers = parser.add_subparsers(dest="command")
+            for module in HANDLERS.values():
+                module.register(subparsers)
+            for command in ["install", "preview", "status", "version"]:
+                subparsers.add_parser(command)
+            parser.print_help()
+            return 0
+        return installer.main(argv)
+    parser = argparse.ArgumentParser(prog="atk")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    for module in HANDLERS.values():
+        module.register(subparsers)
+    args = parser.parse_args(argv)
+    try:
+        emit(HANDLERS[args.command].execute(args), args.json)
+        return 0
+    except UserActionRequired as exc:
+        print(f"atk: {exc}", file=sys.stderr)
+        return 2
+    except ExecutionFailed as exc:
+        print(f"atk: {exc}", file=sys.stderr)
+        return exc.returncode if exc.returncode > 0 else 1
+    except KeyboardInterrupt:
+        print("Evaluation interrupted; partial results were preserved.", file=sys.stderr)
+        return 130
+    except (OSError, ValueError) as exc:
+        print(f"atk: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"atk: unexpected error: {exc}", file=sys.stderr)
+        return 1

agent_tune_kit-2.2.0/agent_tune_kit/cli/output.py

@@ -0,0 +1,11 @@
+import json
+
+
+def emit(result, json_output=False):
+    if json_output:
+        print(json.dumps(result, ensure_ascii=False))
+    else:
+        for key, value in result.items():
+            if key == "browser_open":
+                value = "ok" if value else "skipped"
+            print(f"{key}={value}")

agent_tune_kit-2.2.0/agent_tune_kit/cli/results.py

@@ -0,0 +1,99 @@
+from agent_tune_kit import results
+from agent_tune_kit.execution import run_rule
+
+
+def register(subparsers):
+    commands = subparsers.add_parser("results", help="inspect and judge versioned results").add_subparsers(
+        dest="action", required=True
+    )
+    calibration = commands.add_parser(
+        "calibrate", help="check a judge against reviewed outputs without running the Agent"
+    )
+    calibration.add_argument("--samples-path", required=True)
+    calibration.add_argument("--output-path", required=True)
+    mode = calibration.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--rule-path")
+    mode.add_argument("--judgments-path")
+    calibration.add_argument("--judge-id")
+    calibration.add_argument("--instructions")
+    calibration.add_argument("--python")
+    calibration.add_argument("--json", action="store_true")
+    for name in ["inspect", "run-rule", "apply-judgments", "compare", "evidence", "import-evidence"]:
+        parser = commands.add_parser(name)
+        parser.add_argument("--results-dir", default=".atk/results")
+        parser.add_argument("--json", action="store_true")
+        if name != "import-evidence":
+            parser.add_argument("--version")
+        if name == "run-rule":
+            parser.add_argument("--rule-path", default=".atk/runner/failure_rule.py")
+            parser.add_argument("--python")
+        elif name == "apply-judgments":
+            parser.add_argument("--judgments-path", required=True)
+            parser.add_argument("--source-results")
+        elif name == "compare":
+            parser.add_argument("--ids", nargs="+", required=True)
+        elif name == "import-evidence":
+            parser.add_argument("--source", required=True)
+            parser.add_argument("--adapter", required=True, help="explicit trusted Python adapter (not sandboxed)")
+        elif name == "evidence":
+            parser.add_argument("--execution-dir")
+            parser.add_argument("--atk-id")
+            parser.add_argument("--execution-id")
+            parser.add_argument("--event-id")
+            parser.add_argument("--artifact-id")
+            parser.add_argument("--after-seq", type=int)
+            parser.add_argument("--offset", type=int, default=0)
+            parser.add_argument("--limit", type=int)
+
+
+def execute(args):
+    if args.action == "calibrate":
+        from agent_tune_kit.execution.calibration import launch_calibration
+
+        return launch_calibration(
+            **{
+                key: getattr(args, key)
+                for key in (
+                    "samples_path",
+                    "output_path",
+                    "rule_path",
+                    "judgments_path",
+                    "judge_id",
+                    "instructions",
+                    "python",
+                )
+            }
+        )
+    if args.action == "import-evidence":
+        from agent_tune_kit.results.evidence import import_evidence
+
+        return import_evidence(args.source, args.adapter, args.results_dir)
+    if args.action == "evidence":
+        from agent_tune_kit.results.evidence import query_evidence
+
+        return query_evidence(
+            **{
+                key: getattr(args, key)
+                for key in [
+                    "results_dir",
+                    "version",
+                    "execution_dir",
+                    "atk_id",
+                    "execution_id",
+                    "event_id",
+                    "artifact_id",
+                    "after_seq",
+                    "offset",
+                    "limit",
+                ]
+            }
+        )
+    if args.action == "inspect":
+        return results.inspect_results(args.results_dir, version=args.version)
+    if args.action == "compare":
+        return results.compare_targets(args.ids, args.results_dir, version=args.version)
+    if args.action == "apply-judgments":
+        return results.apply_judgments(
+            args.judgments_path, source_results=args.source_results, results_dir=args.results_dir, version=args.version
+        )
+    return run_rule(rule_path=args.rule_path, results_dir=args.results_dir, python=args.python, version=args.version)

agent_tune_kit-2.2.0/agent_tune_kit/cli/visualize.py

@@ -0,0 +1,55 @@
+import argparse
+import sys
+
+from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.visualize import generate_dataset, generate_failures
+
+from .output import emit
+
+
+def add_options(parser, kind):
+    parser.add_argument("--overwrite", action="store_true")
+    parser.add_argument("--open", dest="open_browser", action="store_true", default=True)
+    parser.add_argument("--no-open", dest="open_browser", action="store_false")
+    parser.add_argument("--json", action="store_true")
+    if kind == "dataset":
+        parser.add_argument("--dataset-path", default=".atk/datasets/dataset.csv")
+    else:
+        parser.add_argument("--results-dir", default=".atk/results")
+        parser.add_argument("--version")
+        parser.add_argument("--no-report", action="store_true")
+        parser.add_argument("--no-history", action="store_true")
+
+
+def register(subparsers):
+    commands = subparsers.add_parser("visualize", help="generate offline review pages").add_subparsers(
+        dest="action", required=True
+    )
+    for kind in ["dataset", "failures"]:
+        add_options(commands.add_parser(kind), kind)
+
+
+def execute(args):
+    options = dict(overwrite=args.overwrite, open_browser=args.open_browser)
+    if args.action == "dataset":
+        return generate_dataset(args.dataset_path, **options)
+    return generate_failures(
+        args.results_dir, no_report=args.no_report, no_history=args.no_history, version=args.version, **options
+    )
+
+
+def legacy_main(kind, argv=None):
+    parser = argparse.ArgumentParser()
+    add_options(parser, kind)
+    args = parser.parse_args(argv)
+    args.action = kind
+    try:
+        result = execute(args)
+        emit(result)
+        return 0
+    except UserActionRequired as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"Unexpected HTML generation error: {exc}", file=sys.stderr)
+        return 1

agent_tune_kit-2.2.0/agent_tune_kit/datasets/__init__.py

@@ -0,0 +1,4 @@
+from .prepare import prepare_dataset
+from .updates import inspect_dataset, update_dataset
+
+__all__ = ["prepare_dataset", "inspect_dataset", "update_dataset"]

agent_tune_kit-2.2.0/agent_tune_kit/datasets/prepare.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.utils.csv_io import parse_csv, write_csv_atomic
+from agent_tune_kit.workspace import DATASET_PATH
+
+from .truth import TRUTH_FIELD
+from .validation import validate_dataset_rows
+
+
+def prepare_dataset(source, dataset_path=DATASET_PATH, *, append=False, overwrite=False):
+    source, target = Path(source), Path(dataset_path)
+    fields, rows = parse_csv(source)
+    old_fields, old_rows = parse_csv(target) if target.exists() else ([], [])
+    if append and not target.exists():
+        raise UserActionRequired("Append requires an existing canonical dataset.")
+    if append:
+        validate_dataset_rows(old_fields, old_rows)
+        if set(fields) - {"atk_id", TRUTH_FIELD} != set(old_fields) - {"atk_id", TRUTH_FIELD}:
+            raise UserActionRequired("Append fields differ; confirm the field mapping before appending.")
+        if TRUTH_FIELD in fields and TRUTH_FIELD not in old_fields:
+            old_fields = old_fields + [TRUTH_FIELD]
+    if "atk_id" not in fields:
+        fields = fields + ["atk_id"]
+        start = max((int(row["atk_id"]) for row in old_rows), default=0) + 1 if append else 1
+        for index, row in enumerate(rows, start):
+            row["atk_id"] = str(index)
+    validate_dataset_rows(fields, rows)
+    if append:
+        fields, rows = old_fields, old_rows + rows
+        validate_dataset_rows(fields, rows)
+    if old_fields == fields and old_rows == rows:
+        return {"dataset": str(target), "rows": len(rows), "reused": True}
+    if target.exists() and not (append or overwrite):
+        raise UserActionRequired(
+            f"Refusing to overwrite different canonical content: {target}; confirm and use --overwrite."
+        )
+    write_csv_atomic(target, fields, rows)
+    return {"dataset": str(target), "rows": len(rows), "reused": False}