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

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.4.1",
+  "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.1 → agent_tune_kit-2.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.4.1
+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.
 
@@ -154,16 +147,18 @@ Run `atk trace --help` to check whether your CLI supports trace tuning. If the c
 - **Langfuse v4**. Use `$atk-trace-init` to record project settings and configure read-only access on first setup. Configuration references credentials by environment-variable name. Then send `$atk-trace-capture Download session <session-id> from <start time> to <end time>`.
 - **Local files**. Send `$atk-trace-capture Import traces for session <session-id> from <file path>, with source <source>`. You can also provide files with verifiable ties to the session during analysis and let detection import them. Analyze an already archived session directly.
 
-The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK adds `.atk/traces/` to the project's `.gitignore`.
+The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK checks whether Git ignores `.atk/traces/` and adds a rule to the project's `.gitignore` if needed.
+
+`$atk-trace-init` infers and saves the tuning scope from project documents and implementation; later detection, diagnosis, repair and verification use it. No manual configuration is required. You can also say "For this run, focus on this project or component." When you skip initialization, analysis fills in the necessary context and explains any unresolved boundaries.
 
 ### 2. Analyze and Review Evidence
 
 ```text
-$atk-trace-detect Check whether session <session-id> completed its task correctly. List issues, evidence, and what you did not inspect.
+$atk-trace-detect Analyze session <session-id> for issues actionable within this project. List evidence and what you did not inspect.
 $atk-visualize-trace Open the execution lanes for session <session-id> and jump from issues to the relevant trace segments and evidence fields.
 ```
 
-Detection retains issues with serious impact, recurrence, direct relevance to your stated focus, or a concrete implementation improvement lead, and explains the retention reason, evidence and inspection scope. Implementation leads include code, configuration, tool contracts, Prompt and Skill; an unresolved cause can proceed to diagnosis. Minor observations with none of these reasons are not saved separately. No retained issues does not prove the session was correct.
+By default, detection retains evidence-backed issues worth pursuing that have a project mechanism, an improvement direction and a minimal verification approach; the root cause may still be uncertain. It explains out-of-scope findings and missing actionability evidence, and still calls attention to serious problems. You can explicitly request a comprehensive quality audit or investigation of a specific symptom without an existing improvement lead. No retained issues does not prove the session was correct.
 
 The capture, detect, diagnose, optimize and verify Skills generate or update `.atk/traces/<session_id>/preview.html` at stage end without opening a browser. Use `$atk-visualize-trace` when you want to open it; refresh an already open page after the file changes. Initialization has no session trace and does not generate an empty page.
 
@@ -176,11 +171,13 @@ Use Trace IDs to locate evidence within the session and open issue details to re
 ```text
 $atk-trace-diagnose Investigate session <session-id> and propose repair and verification plans.
 $atk-trace-diagnose Investigate ISSUE-001 in session <session-id> and propose a repair and verification plan.
-$atk-trace-optimize Implement the selected plan for ISSUE-001 in session <session-id>.
+$atk-trace-optimize Prepare a detailed implementation plan for ISSUE-001 in session <session-id>, then implement after confirmation.
 $atk-trace-verify Verify the candidate for ISSUE-001 in session <session-id> and check relevant behavior that should still work.
 ```
 
-Without specified issues, diagnosis reviews all available session traces and works through existing and newly found issues, prioritizing causes directly related to project code, configuration, tool contracts, Prompt or Skill. Findings established as unrelated to the existing implementation may be skipped with an explanation. Findings with uncertain relevance remain open for investigation. Specified issues or concrete symptoms limit the investigation scope. You can start directly with diagnosis without a separate detection invocation.
+`$atk-trace-optimize` first lists the files, exact modification locations, before/after behavior and supporting checks in Codex. Discuss adjustments in chat; only after you confirm the final version does it save the detailed plan and edit the code. Material scope expansion requires another confirmation; an unchanged confirmed plan does not. Draft discussion stays in chat by default, while the session preview shows the final plan and actual changes.
+
+Without specified issues, diagnosis reviews all available session traces, selects new issues within the tuning scope and reviews each existing issue. Findings established as unrelated to the implementation may be excluded with their reasons and history preserved; existing issues with uncertain relevance are not simply deleted. Specified issues or concrete symptoms define the investigation scope, and a temporary focus does not permanently exclude other issues. You can start directly with diagnosis without a separate detection invocation.
 
 Diagnoses and verification conclusions are saved per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the verification outcome is `inconclusive`. Investigation results identify unread ranges and evidence gaps. As new issues surface, work through them individually or start another analysis with a new session trace.
 

{agent_tune_kit-2.4.1 → 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.
 
@@ -140,16 +133,18 @@ Run `atk trace --help` to check whether your CLI supports trace tuning. If the c
 - **Langfuse v4**. Use `$atk-trace-init` to record project settings and configure read-only access on first setup. Configuration references credentials by environment-variable name. Then send `$atk-trace-capture Download session <session-id> from <start time> to <end time>`.
 - **Local files**. Send `$atk-trace-capture Import traces for session <session-id> from <file path>, with source <source>`. You can also provide files with verifiable ties to the session during analysis and let detection import them. Analyze an already archived session directly.
 
-The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK adds `.atk/traces/` to the project's `.gitignore`.
+The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK checks whether Git ignores `.atk/traces/` and adds a rule to the project's `.gitignore` if needed.
+
+`$atk-trace-init` infers and saves the tuning scope from project documents and implementation; later detection, diagnosis, repair and verification use it. No manual configuration is required. You can also say "For this run, focus on this project or component." When you skip initialization, analysis fills in the necessary context and explains any unresolved boundaries.
 
 ### 2. Analyze and Review Evidence
 
 ```text
-$atk-trace-detect Check whether session <session-id> completed its task correctly. List issues, evidence, and what you did not inspect.
+$atk-trace-detect Analyze session <session-id> for issues actionable within this project. List evidence and what you did not inspect.
 $atk-visualize-trace Open the execution lanes for session <session-id> and jump from issues to the relevant trace segments and evidence fields.
 ```
 
-Detection retains issues with serious impact, recurrence, direct relevance to your stated focus, or a concrete implementation improvement lead, and explains the retention reason, evidence and inspection scope. Implementation leads include code, configuration, tool contracts, Prompt and Skill; an unresolved cause can proceed to diagnosis. Minor observations with none of these reasons are not saved separately. No retained issues does not prove the session was correct.
+By default, detection retains evidence-backed issues worth pursuing that have a project mechanism, an improvement direction and a minimal verification approach; the root cause may still be uncertain. It explains out-of-scope findings and missing actionability evidence, and still calls attention to serious problems. You can explicitly request a comprehensive quality audit or investigation of a specific symptom without an existing improvement lead. No retained issues does not prove the session was correct.
 
 The capture, detect, diagnose, optimize and verify Skills generate or update `.atk/traces/<session_id>/preview.html` at stage end without opening a browser. Use `$atk-visualize-trace` when you want to open it; refresh an already open page after the file changes. Initialization has no session trace and does not generate an empty page.
 
@@ -162,11 +157,13 @@ Use Trace IDs to locate evidence within the session and open issue details to re
 ```text
 $atk-trace-diagnose Investigate session <session-id> and propose repair and verification plans.
 $atk-trace-diagnose Investigate ISSUE-001 in session <session-id> and propose a repair and verification plan.
-$atk-trace-optimize Implement the selected plan for ISSUE-001 in session <session-id>.
+$atk-trace-optimize Prepare a detailed implementation plan for ISSUE-001 in session <session-id>, then implement after confirmation.
 $atk-trace-verify Verify the candidate for ISSUE-001 in session <session-id> and check relevant behavior that should still work.
 ```
 
-Without specified issues, diagnosis reviews all available session traces and works through existing and newly found issues, prioritizing causes directly related to project code, configuration, tool contracts, Prompt or Skill. Findings established as unrelated to the existing implementation may be skipped with an explanation. Findings with uncertain relevance remain open for investigation. Specified issues or concrete symptoms limit the investigation scope. You can start directly with diagnosis without a separate detection invocation.
+`$atk-trace-optimize` first lists the files, exact modification locations, before/after behavior and supporting checks in Codex. Discuss adjustments in chat; only after you confirm the final version does it save the detailed plan and edit the code. Material scope expansion requires another confirmation; an unchanged confirmed plan does not. Draft discussion stays in chat by default, while the session preview shows the final plan and actual changes.
+
+Without specified issues, diagnosis reviews all available session traces, selects new issues within the tuning scope and reviews each existing issue. Findings established as unrelated to the implementation may be excluded with their reasons and history preserved; existing issues with uncertain relevance are not simply deleted. Specified issues or concrete symptoms define the investigation scope, and a temporary focus does not permanently exclude other issues. You can start directly with diagnosis without a separate detection invocation.
 
 Diagnoses and verification conclusions are saved per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the verification outcome is `inconclusive`. Investigation results identify unread ranges and evidence gaps. As new issues surface, work through them individually or start another analysis with a new session trace.
 

{agent_tune_kit-2.4.1 → 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 仓库根目录**运行以下命令。更新源码后可重新执行，包括版本号未变的情况。
 
@@ -140,16 +133,18 @@ $atk-report
 - **Langfuse v4**。首次接入可用 `$atk-trace-init` 记录项目和只读来源配置。配置只引用凭据的环境变量名。然后发送 `$atk-trace-capture 下载 <session-id> 的会话，时间范围是 <开始时间> 到 <结束时间>`。
 - **本地文件**。发送 `$atk-trace-capture 从 <文件路径> 导入 <session-id> 的轨迹，来源是 <来源>`。也可在分析时提供可验证会话归属的文件，由分析流程导入。已归档的会话可直接分析。
 
-采集步骤负责下载或导入。保存前确认哪些正文可以留存、哪些字段需要脱敏。`.atk/traces/` 会加入项目的 `.gitignore`。
+采集步骤负责下载或导入。保存前确认哪些正文可以留存、哪些字段需要脱敏。ATK 确保 Git 忽略 `.atk/traces/`，需要时会补写项目的 `.gitignore`。
+
+`$atk-trace-init` 会根据项目说明和实现自动识别并保存调优范围，后续分析、诊断、修复和验证沿用该范围。无需手工配置；也可直接说明“本轮只看某个项目或组件”。跳过初始化时，分析流程会自动补齐必要上下文，无法确定的边界会明确说明。
 
 ### 2. 分析并查看证据
 
 ```text
-$atk-trace-detect 分析 <session-id> 的任务结果是否正确，列出问题、证据和未检查的范围。
+$atk-trace-detect 分析 <session-id>，筛选当前项目可调优的问题，列出证据和未检查的范围。
 $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关轨迹片段和证据字段。
 ```
 
-分析保留影响严重、反复出现、与你明确关注点相关，或有具体实现改进线索的问题，并说明保留理由、证据和检查范围。实现线索包括代码、配置、工具契约、Prompt 和 Skill；根因尚未确定也可进入后续诊断。轻微且无上述保留理由的观察不单独记录，没有保留问题不代表会话完全正确。
+分析默认保留有证据、值得投入，且能说明项目机制、改进方向和最小验证办法的问题；根因尚未确定也可进入后续诊断。范围外的问题说明未纳入原因，暂缺可处理性证据的问题说明缺口，严重问题仍会提示。需要全面质量审计或调查某个具体症状时可直接提出，不限于已有改进线索。没有保留问题不代表会话完全正确。
 
 采集、分析、诊断、修复和验证 Skill 在阶段结束后默认生成或更新 `.atk/traces/<session_id>/preview.html`，不自动打开浏览器。需要打开时使用 `$atk-visualize-trace`；已打开的页面在文件更新后需刷新。初始化没有会话轨迹，不生成空页面。
 
@@ -162,11 +157,13 @@ $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关
 ```text
 $atk-trace-diagnose 调查 <session-id>，给出修复和验证方案。
 $atk-trace-diagnose 调查 <session-id> 的 ISSUE-001，给出修复和验证方案。
-$atk-trace-optimize 实施 <session-id> 的 ISSUE-001 已选定的方案。
+$atk-trace-optimize 为 <session-id> 的 ISSUE-001 准备详细修改方案，确认后实施。
 $atk-trace-verify 验证 <session-id> 的 ISSUE-001 对应候选，并检查相关正常行为。
 ```
 
-未指定问题时，调查默认检查会话中可用的全部轨迹，逐项处理已记录和新发现的问题，优先定位与项目代码、配置、工具契约、Prompt 或 Skill 直接相关的原因。证据确认与现有实现无关的问题可以忽略，并说明理由。关联尚不明确的问题保留待查。指定问题或具体症状时，按指定范围调查。可以直接从调查开始，无需先单独执行检测。
+`$atk-trace-optimize` 会先在 Codex 中列出具体文件、修改位置、前后行为和配套验证。你可以在对话中调整方案；确认最终版本后，才保存详细实施方案并修改代码。实质扩大范围时会再次确认，同一已确认方案无需重复确认。讨论稿默认保留在对话中；会话预览展示最终方案与实际修改。
+
+未指定问题时，调查默认检查会话中可用的全部轨迹，按调优范围筛选新问题，并逐项审阅已记录的问题。证据确认与现有实现无关的问题可以排除，并保留理由和历史；已记录但关联尚不明确的问题不会直接删除。指定问题或具体症状时，按指定范围调查，临时收窄范围不会永久排除其他问题。可以直接从调查开始，无需先单独执行检测。
 
 诊断和验证结论分别按问题保存。证据不足以确认实际加载的候选或关键验证条件时，验证效果记为 `inconclusive`（无法判断）。调查结果会说明未检查的范围和证据缺口。后续发现新的问题，可继续按问题处理，或用新会话的轨迹开始下一次分析。
 

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

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

{agent_tune_kit-2.4.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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)