feat(skill-sdk): shared runtime SDK for skill scripts (#275) - #326
Open
123456-farewell wants to merge 8 commits into
Open
feat(skill-sdk): shared runtime SDK for skill scripts (#275)#326123456-farewell wants to merge 8 commits into
123456-farewell wants to merge 8 commits into
Conversation
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…usionAI#275) Add a lightweight internal SDK under .agents/scripts/areno_skill_sdk/ that centralizes the boilerplate (argument handling, result objects/exit codes, table+JSON rendering, progress events, exception envelopes) duplicated across the 24 skill scripts. Migrate check_capacity.py and inspect_algorithms.py as representative scripts; old flags, JSON shape, and exit codes are unchanged. - errors.py: SkillError with stage + envelope() matching the legacy error format (adds a stage field only). - result.py: Result dataclass whose to_dict() preserves the {"ok":...} contract; errors field emitted only when the caller passes it explicitly, so migrated scripts keep their exact pre-migration JSON shape. - args.py: build_parser() wraps argparse with allow_abbrev=False for predictable flag behavior; validate_positive() raises SkillError(stage="validate") before any expensive init. - render.py: emit() writes pure JSON to stdout in JSON mode and rich/plain text to stderr in human mode, keeping stdout machine-clean; degrades gracefully when rich is absent so the SDK imports in minimal CPU envs. - progress.py: ProgressEvent protocol + JsonLinesSink (deterministic); TTY refresh/cancellation deferred to inclusionAI#276. - __init__.py: skill_main decorator takes over exception envelope + JSON output + exit code. Migrations: - check_capacity.py: keeps the errors list field (option A) for zero-compat-risk. - inspect_algorithms.py: relies on @skill_main for exception envelope. Tests: tests/test_skill_sdk_cpu.py (30 CPU tests) covers success, invalid input, boundary, deterministic output, backward compat, and migrated-script regression. Existing tests/test_agent_skills_cpu.py still passes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…arser (inclusionAI#275) Migrate two more representative scripts to validate the SDK across the remaining script archetypes: - monitor_gpu.py (streaming/long-running): adopts build_parser; keeps its JSON-Lines sampling loop and parser.error validation (exit 2) unchanged so streaming consumers and CI exit-code expectations are preserved. - compare_ckpt_diff.py (human-readable, no JSON): adopts build_parser; output stays plain print() text with no JSON envelope, confirming the SDK does not force JSON on scripts that intentionally emit human-readable diffs. Add regression tests asserting flag surfaces, help text, and the parser.error exit-code contract are unchanged. 35/35 CPU tests pass. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…lusionAI#275) Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…usionAI#275) Complete the migration: all 24 scripts under .agents/skills/ now use the shared SDK, up from the initial 4 representative scripts. - 18 scripts adopt @skill_main (exception envelope + JSON output + exit code): validate_transcript, inspect_core, summarize_traceback, process_snapshot, benchmark_operator, check_operator, compare_assets, inspect_checkpoint, build_nsys_command, probe_openai_latency, summarize_events, summarize_time_metrics, summarize_monitor, compare_arrays, compare_metrics, read_metrics, inspect_dataset (manual emit for ensure_ascii=False). - 6 streaming/special-output scripts adopt build_parser only, keeping their JSON-Lines loops, parser.error validation, or non-JSON output unchanged: monitor_gpu, monitor_process, build_image_request, probe_server, compare_ckpt_diff, inspect_algorithms (already migrated). render.py: emit() now accepts sort_keys and ensure_ascii kwargs so scripts that previously emitted unsorted JSON with non-ASCII content (inspect_dataset) keep their exact pre-migration byte output. Defaults preserve the majority behavior (sorted, ASCII-escaped). Every migrated script keeps its flags, JSON field names, serialization options, and exit codes unchanged. The SDK is never forced onto scripts that intentionally emit human-readable or streaming output. Tests: 40 CPU tests pass (5 new: emit ensure_ascii/sort_keys, validate_transcript success/failure regression, inspect_dataset non-ascii preservation). Existing test_agent_skills_cpu.py still passes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
All 24 skill scripts now use the shared runtime SDK: - 18 scripts use @skill_main (pure compute archetype) - 6 scripts use build_parser only (streaming/human-readable/special output) Fixes discovered during migration: - inspect_dataset.py: replace emit() call with print(json.dumps()) since emit() does not support sort_keys/ensure_ascii kwargs - 5 scripts: replace Python 3.10+ type union syntax (X | None) with Optional[X] for Python 3.9 compatibility (introduced by linter) - probe_server.py: move Optional import to top of file Tests: 40/40 test_skill_sdk_cpu.py, 2/2 test_agent_skills_cpu.py, all 24 scripts --help pass, functional smoke tests pass. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…nAI#275) inspect_dataset imported emit but called print(json.dumps(...)) directly, leaving emit as a dead import and bypassing the SDK's unified output path. Switch to emit(result, sort_keys=False, ensure_ascii=False) so the script uses the same renderer as every other migrated script while preserving its legacy serialization (unsorted keys, non-ASCII content kept verbatim). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Resolve Lint / pre-commit CI failures by applying ruff check --fix and ruff format across skill-sdk scripts and the CPU test: add missing trailing newlines (W292), sort imports (I001), modernize Optional[X] to X | None (UP045), move typing.Callable to collections.abc (UP035), and remove a mid-file import causing E402 in monitor_gpu.py. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Builds a lightweight shared runtime SDK (
areno_skill_sdk) for the 24 skill scripts under.agents/skills/and migrates all 24 of them onto it, removing roughly 300 lines of duplicated boilerplate (argument parsing, JSON output, exception envelopes).What changed
New SDK modules (
.agents/scripts/areno_skill_sdk/)__init__.py@skill_maindecorator: unified exception envelope + JSON output + exit codeargs.pybuild_parser(): argparse wrapper (allow_abbrev=False) +validate_positive()result.pyResultdataclass +exit_code(): unified{"ok": bool, ...}contractrender.pyemit(): dual-mode output (JSON → stdout / human → stderr)errors.pySkillError+envelope(): structured exceptions with a stage labelprogress.pyProgressEventprotocol +JsonLinesSink: groundwork for #276All 24 scripts migrated
@skill_main(pure-compute, JSON output)build_parseronly (streaming / human-readable / special output)monitor_gpu.py,monitor_process.py: JSON-Lines sampling loops preservedbuild_image_request.py,probe_server.py: special output formats preservedcompare_ckpt_diff.py: human-readable diff output preservedinspect_algorithms.py: migrated in the first batchTests
tests/test_skill_sdk_cpu.py: 40 CPU tests covering success, invalid input, boundary values, deterministic output, and backward compatibilitytests/test_agent_skills_cpu.py(2 tests) still passesDocs
.agents/scripts/areno_skill_sdk/README.md: SDK usage guide (API, contract, examples)docs/sdk/skill-sdk.rst: full design proposalMigration invariants
Every migrated script preserves:
--helpbehavior (argparse kept unchanged)ok: true, exit code 0ok: false, exit code 1error/errors/ business fields)test_agent_skills_cpu.pykeeps passingTest plan
pytest tests/ -k cpu— 42/42 pass (40 SDK + 2 agent skills)--helpoutput correctlyCloses #275