agent-tune-kit 2.4.2__tar.gz → 2.4.3__tar.gz

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Local Codex plugin for batch Agent evaluation and session trace tuning with evidence-backed issues, focused changes, verification and offline review.",
   "author": {
     "name": "hustyichi",

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.4.2
+Version: 2.4.3
 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
@@ -25,7 +25,7 @@ Agent Tune Kit is a **local Codex plugin** for tuning an Agent's prompts, code,
 
 ## Install and Enable
 
-Run these commands in your terminal to install ATK and its bundled Skills.
+Run these commands in your terminal to install ATK from PyPI and set up its bundled Skills.
 
 ```sh
 uv tool install agent-tune-kit
@@ -35,14 +35,7 @@ atk install
 In Codex, enter `/plugins`, select and enable `Agent Tune Kit`, then restart Codex and open a new session.
 
 <details>
-<summary>Install with pipx or from local source</summary>
-
-To install with pipx, run the following commands.
-
-```sh
-pipx install agent-tune-kit
-atk install
-```
+<summary>Install from local source</summary>
 
 To install from local source, update your chosen branch and run these commands from the **ATK repository root**. Rerun them after source updates, including when the version stays the same.
 

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/README.en.md

@@ -11,7 +11,7 @@ Agent Tune Kit is a **local Codex plugin** for tuning an Agent's prompts, code,
 
 ## Install and Enable
 
-Run these commands in your terminal to install ATK and its bundled Skills.
+Run these commands in your terminal to install ATK from PyPI and set up its bundled Skills.
 
 ```sh
 uv tool install agent-tune-kit
@@ -21,14 +21,7 @@ atk install
 In Codex, enter `/plugins`, select and enable `Agent Tune Kit`, then restart Codex and open a new session.
 
 <details>
-<summary>Install with pipx or from local source</summary>
-
-To install with pipx, run the following commands.
-
-```sh
-pipx install agent-tune-kit
-atk install
-```
+<summary>Install from local source</summary>
 
 To install from local source, update your chosen branch and run these commands from the **ATK repository root**. Rerun them after source updates, including when the version stays the same.
 

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/README.md

@@ -11,7 +11,7 @@ Agent Tune Kit 是一个**本地 Codex 插件**，用于调优 Agent 的提示
 
 ## 安装与启用
 
-在终端运行以下命令安装 ATK 和配套 Skills。
+在终端运行以下命令，从 PyPI 安装 ATK，再安装配套 Skills。
 
 ```sh
 uv tool install agent-tune-kit
@@ -21,14 +21,7 @@ atk install
 在 Codex 中输入 `/plugins`，选择并启用 `Agent Tune Kit`，然后重启 Codex 并新建会话。
 
 <details>
-<summary>使用 pipx 或本地源码安装</summary>
-
-用 pipx 安装。
-
-```sh
-pipx install agent-tune-kit
-atk install
-```
+<summary>从本地源码安装</summary>
 
 从本地源码安装时，先更新所需分支，再在 **ATK 仓库根目录**运行以下命令。更新源码后可重新执行，包括版本号未变的情况。
 

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/__init__.py

@@ -1,3 +1,3 @@
 """Agent Tune Kit package."""
 
-__version__ = "2.4.2"
+__version__ = "2.4.3"

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/dataset.py

@@ -1,9 +1,14 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+from typing import Any
+
 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):
+def add_options(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--dataset-path", default=str(DATASET_PATH))
     parser.add_argument("--field", default="ground_truth")
     parser.add_argument("--input-fields", nargs="+")
@@ -14,10 +19,11 @@ def add_options(parser):
     parser.add_argument("--json", action="store_true")
 
 
-def register(subparsers):
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     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))
@@ -25,16 +31,19 @@ def register(subparsers):
     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):
+def execute(args: argparse.Namespace) -> Mapping[str, object]:
     if args.action == "prepare":
         return datasets.prepare_dataset(args.source, args.dataset_path, append=args.append, overwrite=args.overwrite)
-    options = dict(
+
+    options: dict[str, Any] = dict(
         dataset_path=args.dataset_path,
         direct=args.direct,
         review_path=args.review_path,
@@ -45,37 +54,3 @@ def execute(args):
     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.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/evaluation.py

@@ -1,21 +1,28 @@
+from __future__ import annotations
+
+import argparse
+
 from agent_tune_kit.execution import run_evaluation
+from agent_tune_kit.models import EvaluationResult
 
 
-def register(subparsers):
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     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)
+
     selection = parser.add_mutually_exclusive_group()
     selection.add_argument("--only-failures", action="store_true")
     selection.add_argument("--ids", nargs="+", help="select canonical samples by stable atk_id before offset/limit")
+
     parser.add_argument("--no-progress", action="store_true")
     parser.add_argument("--python")
     parser.add_argument("--json", action="store_true")
 
 
-def execute(args):
+def execute(args: argparse.Namespace) -> EvaluationResult:
     return run_evaluation(
         **{
             key: getattr(args, key)

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/main.py

@@ -1,7 +1,10 @@
 """Public command dispatch; business behavior lives in domain packages."""
 
+from __future__ import annotations
+
 import argparse
 import sys
+from collections.abc import Sequence
 
 from agent_tune_kit import installer
 from agent_tune_kit.errors import UserActionRequired
@@ -13,12 +16,8 @@ from .output import emit
 HANDLERS = {"dataset": dataset, "eval": evaluation, "results": results, "visualize": visualize, "trace": trace}
 
 
-def main(argv=None):
+def main(argv: Sequence[str] | None = None) -> int:
     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")
@@ -30,6 +29,7 @@ def main(argv=None):
             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():

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/output.py

@@ -1,7 +1,8 @@
 import json
+from collections.abc import Mapping
 
 
-def emit(result, json_output=False):
+def emit(result: Mapping[str, object], json_output: bool = False) -> None:
     if json_output:
         print(json.dumps(result, ensure_ascii=False))
     else:

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/results.py

@@ -1,11 +1,19 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+
 from agent_tune_kit import results
 from agent_tune_kit.execution import run_rule
+from agent_tune_kit.execution.calibration import launch_calibration
+from agent_tune_kit.results.evidence import import_evidence, query_evidence
 
 
-def register(subparsers):
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     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"
     )
@@ -18,12 +26,14 @@ def register(subparsers):
     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")
@@ -46,10 +56,8 @@ def register(subparsers):
             parser.add_argument("--limit", type=int)
 
 
-def execute(args):
+def execute(args: argparse.Namespace) -> Mapping[str, object]:
     if args.action == "calibrate":
-        from agent_tune_kit.execution.calibration import launch_calibration
-
         return launch_calibration(
             **{
                 key: getattr(args, key)
@@ -64,13 +72,11 @@ def execute(args):
                 )
             }
         )
-    if args.action == "import-evidence":
-        from agent_tune_kit.results.evidence import import_evidence
 
+    if args.action == "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
 
+    if args.action == "evidence":
         return query_evidence(
             **{
                 key: getattr(args, key)
@@ -88,12 +94,15 @@ def execute(args):
                 ]
             }
         )
+
     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.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/trace.py

@@ -1,14 +1,22 @@
 """Explicit session commands; analysis and effect judgments belong to the host."""
 
+from __future__ import annotations
+
+import argparse
 import json
+from collections.abc import Mapping
 from pathlib import Path
+from typing import Any, cast
 
+from agent_tune_kit.models import IssueUpdate, PathInput
 from agent_tune_kit.traces import categories, records, store
 from agent_tune_kit.traces.capture import fetch_session, import_session
+from agent_tune_kit.traces.migrate import migrate
+from agent_tune_kit.traces.projects import discover_projects, load_projects, save_project
 from agent_tune_kit.traces.query import overview, search, show
 
 
-def read_json(path):
+def read_json(path: PathInput | None) -> dict[str, Any] | None:
     if path is None:
         return None
     value = json.loads(Path(path).read_text(encoding="utf-8"))
@@ -17,23 +25,25 @@ def read_json(path):
     return value
 
 
-def add_session_options(parser):
+def add_session_options(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--project-root", default=".")
     parser.add_argument("--session-id", required=True)
     parser.add_argument("--source", help="JSON file with type, instance, project and environment")
     parser.add_argument("--json", action="store_true")
 
 
-def register(subparsers):
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     commands = subparsers.add_parser(
         "trace", help="capture and investigate one session, independently of batch evaluation"
     )
     actions = commands.add_subparsers(dest="action", required=True)
+
     init = actions.add_parser("init", help="save project context and non-secret source configuration")
     init.add_argument("--project-root", default=".")
     init.add_argument("--config", help="non-secret configuration JSON file")
     init.add_argument("--project-file", help="project context Markdown file")
     init.add_argument("--json", action="store_true")
+
     project = actions.add_parser("project", help="discover, list or update workspace projects")
     project.add_argument("--project-root", default=".")
     mode = project.add_mutually_exclusive_group(required=True)
@@ -41,12 +51,14 @@ def register(subparsers):
     mode.add_argument("--list", action="store_true")
     mode.add_argument("--data")
     project.add_argument("--json", action="store_true")
+
     category = actions.add_parser("category", help="list or update the project issue category vocabulary")
     category.add_argument("--project-root", default=".")
     mode = category.add_mutually_exclusive_group(required=True)
     mode.add_argument("--list", action="store_true", help="list categories with per-session issue counts")
     mode.add_argument("--data", help="category JSON; revising the vocabulary requires its current revision")
     category.add_argument("--json", action="store_true")
+
     for action in [
         "migrate",
         "fetch",
@@ -110,33 +122,34 @@ def register(subparsers):
             parser.add_argument("--expected-revision", type=int)
 
 
-def execute(args):
+def execute(args: argparse.Namespace) -> Mapping[str, object]:
     if args.action == "project":
-        from agent_tune_kit.traces.projects import discover_projects, load_projects, save_project
-
         if args.discover:
             return discover_projects(args.project_root)
         if args.list:
             return load_projects(store.trace_root(args.project_root))
         return save_project(args.project_root, read_json(args.data))
+
     if args.action == "init":
         text = Path(args.project_file).read_text(encoding="utf-8") if args.project_file else None
         return store.init_workspace(args.project_root, config=read_json(args.config), project_text=text)
+
     if args.action == "category":
         if args.list:
             return categories.list_categories(args.project_root)
         return categories.save_category(args.project_root, read_json(args.data))
+
     source = read_json(args.source)
     if args.action == "migrate":
-        from agent_tune_kit.traces.migrate import migrate
-
         return migrate(args.project_root, args.session_id, source)
+
     if args.action == "fetch":
         config = read_json(args.config)
         if source is not None:
             if config is None:
-                config = read_json(Path(args.project_root) / ".atk/traces/config.json")
+                config = cast(dict[str, Any], read_json(Path(args.project_root) / ".atk/traces/config.json"))
             config = {**config, "source": source}
+
         return fetch_session(
             args.project_root,
             args.session_id,
@@ -145,10 +158,12 @@ def execute(args):
             to_time=args.to_time,
             retention=read_json(args.retention),
         )
+
     if args.action == "import":
         if source is None:
-            config = read_json(Path(args.project_root) / ".atk/traces/config.json")
+            config = cast(dict[str, Any], read_json(Path(args.project_root) / ".atk/traces/config.json"))
             source = config.get("source")
+
         return import_session(
             args.project_root,
             args.session_id,
@@ -157,21 +172,26 @@ def execute(args):
             association=read_json(args.association),
             retention=read_json(args.retention),
         )
+
     session_dir = store.resolve_session(args.project_root, args.session_id, source)
     if args.action in {"overview", "search", "show"}:
-        options = {"offset": args.offset, "limit": args.limit}
+        options: dict[str, Any] = {"offset": args.offset, "limit": args.limit}
         if args.action == "show":
             return show(session_dir, read_json(args.ref), **options)
+
         options["capture_id"] = args.capture_id
         if args.action == "search":
             return search(session_dir, args.text, **options)
+
         if getattr(args, "trace_id", None):
             options["trace_id"] = args.trace_id
         return overview(session_dir, **options)
+
     if args.action == "status":
         return records.status(session_dir)
     if args.action == "ref":
         return store.evidence_ref(session_dir, args.path, args.pointer)
+
     if args.action == "diagnose":
         return records.save_diagnosis(
             session_dir,
@@ -180,11 +200,14 @@ def execute(args):
             diagnosis_id=args.diagnosis_id,
             expected_revision=args.expected_revision,
         )
+
     data = read_json(args.data)
     if args.action == "issue":
-        return records.save_issue(session_dir, data, dry_run=bool(getattr(args, "dry_run", False)))
+        # prepare_issue validates the command's raw input without rewriting it.
+        return records.save_issue(session_dir, cast(IssueUpdate, data), dry_run=bool(getattr(args, "dry_run", False)))
     if args.action == "detect":
         return records.save_detection(session_dir, data)
+
     if args.action == "change":
         return records.save_change(session_dir, args.issue_id, data)
     return records.save_verification(session_dir, args.issue_id, args.change_id, data)

{agent_tune_kit-2.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/cli/visualize.py

@@ -1,21 +1,23 @@
+from __future__ import annotations
+
 import argparse
-import sys
+from typing import Any
 
-from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.models import VisualizationResult
 from agent_tune_kit.visualize import generate_dataset, generate_failures
 from agent_tune_kit.visualize.trace import generate_trace
 from agent_tune_kit.visualize.traces import generate_traces
 
-from .output import emit
 from .trace import add_session_options, read_json
 
 
-def add_options(parser, kind):
+def add_options(parser: argparse.ArgumentParser, kind: str) -> None:
     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")
     if kind != "trace":
         parser.add_argument("--json", action="store_true")
+
     if kind == "dataset":
         parser.add_argument("--dataset-path", default=".atk/datasets/dataset.csv")
     elif kind == "traces":
@@ -30,7 +32,7 @@ def add_options(parser, kind):
         parser.add_argument("--no-history", action="store_true")
 
 
-def register(subparsers):
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     commands = subparsers.add_parser("visualize", help="generate offline review pages").add_subparsers(
         dest="action", required=True
     )
@@ -39,8 +41,8 @@ def register(subparsers):
         add_options(commands.add_parser(kind, help=helps.get(kind)), kind)
 
 
-def execute(args):
-    options = dict(overwrite=args.overwrite, open_browser=args.open_browser)
+def execute(args: argparse.Namespace) -> VisualizationResult:
+    options: dict[str, Any] = dict(overwrite=args.overwrite, open_browser=args.open_browser)
     if args.action == "dataset":
         return generate_dataset(args.dataset_path, **options)
     if args.action == "traces":
@@ -56,20 +58,3 @@ def execute(args):
     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.4.2 → agent_tune_kit-2.4.3}/agent_tune_kit/datasets/prepare.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.models import DatasetPrepareResult
 from agent_tune_kit.utils.csv_io import parse_csv, write_csv_atomic
 from agent_tune_kit.workspace import DATASET_PATH
 
@@ -8,32 +9,39 @@ from .truth import TRUTH_FIELD
 from .validation import validate_dataset_rows
 
 
-def prepare_dataset(source, dataset_path=DATASET_PATH, *, append=False, overwrite=False):
+def prepare_dataset(
+    source: str | Path, dataset_path: str | Path = DATASET_PATH, *, append: bool = False, overwrite: bool = False
+) -> DatasetPrepareResult:
     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}