change: Implement 7: Document the tool-calling contract, statuses, exit codes and native-process usage #17
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: projects/product-54354138-1#17
Reference in New Issue
Block a user
Rewrote README.md as the delivered tool-calling contract for the calling AI agent and added tests/test_readme.py to keep it synchronized with the implementation.
README.md now documents:
python -m tools.examplewith no Docker, container image or packaging stage, Python >= 3.11, no runtime third-party dependencies.--help: positionalREQUEST.json,-t/--topic,--width,--height,-f/--format(png|ico),-s/--source(defaultwikimedia_commons),-c/--count(1-50, default 10),--download,-o/--output-dir,--resize,--dry-run; width/height documented as minimums and the "document XOR flags" rule.examples/input.json: field table, types, defaults, optionalversion, and the document-level invalid_request rules.status,source,request,items,error; item fields (actual format/width/height,url/file_url,size_bytes), download record, resize fragment and the verified-save failure record.ok=0,dry_run=0,invalid_request=2,no_format=3,no_size=4,access_error=5,partial_download=6, plus why no_match/outage are distinguishable.wikimedia_commons,openverse) with no API keys, tokens or registration, the approved HTTPS host allowlist, and the registry extension point (SourceAdapter,SourceRegistry.register/unregister,build_registry()/default_registry(), host allowlist extension).--downloadwithout--output-diris an invalid request (invalid_request / exit 2), and partial saves are reported aspartial_download(exit 6) withdownload_incompletedetails while saved paths are still reported.pytestplus the compileall/help/smoke commands.tests/test_readme.py asserts the README documents every long option the real parser accepts, the accepted formats, every status with its exit code from STATUS_EXIT_CODES, the response keys, every registered source id, the registry extension names, both product decisions, native-process wording, and the real pytest/compileall/help/smoke commands.
Tests:
Ran the facade check set with .venv/bin on PATH after
prepare_environment(component=tools, mode=restore):pytest -q-> 163 passed, 1 skipped (pre-existing tests/test_live_source.py live-network skip: Wikimedia upload host returns HTTP 429 from this sandbox).python -m compileall -q tools tests-> ok.python -m tools.example --help-> exit 0.python -m tools.example examples/input.json-> exit 0, one JSON dry_run envelope.pytest tests/test_readme.py -q-> 5 passed.Also confirmed
git merge-base --is-ancestor origin/task/1-task HEAD(target branch already integrated, zero diff), so no integration step was required.Progress:
Delivered the documentation slice for issue 9. README.md was a two-line placeholder; it is now the full tool-calling contract: CLI parameters matching
--helpoutput, the JSON request-document form for examples/input.json, the single-document response schema, the fixed status vocabulary with exit codes (ok/dry_run=0, invalid_request=2, no_format=3, no_size=4, access_error=5, partial_download=6), credential-free sources and the registry extension point, the decided --download-without---output-dir invalid-request behaviour, partial_download reporting for incomplete saves, and plain native-process execution with the real pytest entrypoint. Added tests/test_readme.py (5 tests) so CI fails if documentation drifts from build_parser(), STATUS_EXIT_CODES, ACCEPTED_FORMATS or the default registry. No protected facade paths or source behaviour changed; existing obligations preserved (full suite green apart from the pre-existing live-source skip).Published by developer-agent through Tool Backend.
Closes #9
Developer-agent completed implementation and CI passed, but updating the PR title/body failed.
Intended title: change: Implement 7: Document the tool-calling contract, statuses, exit codes and native-process usage
Commit:
2e8e70e765CI: CI passed.
Intended body:
Rewrote README.md as the delivered tool-calling contract for the calling AI agent and added tests/test_readme.py to keep it synchronized with the implementation.
README.md now documents:
python -m tools.examplewith no Docker, container image or packaging stage, Python >= 3.11, no runtime third-party dependencies.--help: positionalREQUEST.json,-t/--topic,--width,--height,-f/--format(png|ico),-s/--source(defaultwikimedia_commons),-c/--count(1-50, default 10),--download,-o/--output-dir,--resize,--dry-run; width/height documented as minimums and the "document XOR flags" rule.examples/input.json: field table, types, defaults, optionalversion, and the document-level invalid_request rules.status,source,request,items,error; item fields (actual format/width/height,url/file_url,size_bytes), download record, resize fragment and the verified-save failure record.ok=0,dry_run=0,invalid_request=2,no_format=3,no_size=4,access_error=5,partial_download=6, plus why no_match/outage are distinguishable.wikimedia_commons,openverse) with no API keys, tokens or registration, the approved HTTPS host allowlist, and the registry extension point (SourceAdapter,SourceRegistry.register/unregister,build_registry()/default_registry(), host allowlist extension).--downloadwithout--output-diris an invalid request (invalid_request / exit 2), and partial saves are reported aspartial_download(exit 6) withdownload_incompletedetails while saved paths are still reported.pytestplus the compileall/help/smoke commands.tests/test_readme.py asserts the README documents every long option the real parser accepts, the accepted formats, every status with its exit code from STATUS_EXIT_CODES, the response keys, every registered source id, the registry extension names, both product decisions, native-process wording, and the real pytest/compileall/help/smoke commands.
Tests:
Ran the facade check set with .venv/bin on PATH after
prepare_environment(component=tools, mode=restore):pytest -q-> 163 passed, 1 skipped (pre-existing tests/test_live_source.py live-network skip: Wikimedia upload host returns HTTP 429 from this sandbox).python -m compileall -q tools tests-> ok.python -m tools.example --help-> exit 0.python -m tools.example examples/input.json-> exit 0, one JSON dry_run envelope.pytest tests/test_readme.py -q-> 5 passed.Also confirmed
git merge-base --is-ancestor origin/task/1-task HEAD(target branch already integrated, zero diff), so no integration step was required.Published by developer-agent through Tool Backend.
README.md is now a complete, non-empty tool-calling contract matching the delivered CLI: native-process invocation, every documented long option/format/source id, the JSON request document, response schema, STATUS_EXIT_CODES with exit values, approved credential-free sources and registry extension point, and both decided download behaviours. tests/test_readme.py runs through the standard pytest entrypoint and passed in CI at the reviewed head SHA (163 passed, 1 pre-existing live-network skip), with the facade help-command acceptance also passing. No protected facade paths were changed.
Acceptance evidence for
2e8e70e765d8577d045d576ad5c11c2e3ec0cea5: