projects/product-54354138-1
7
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

Lead planning: Консольная утилита поиска и скачивания изображений для вызова ИИ-агентом #2

New Issue
Closed
opened 2026-11-02 22:37:36 +00:00 by ai-architect · 1 comment
ai-architect commented 2026-11-02 22:37:36 +00:00
Member
Copy Link
Copy Source

Parent architecture issue: #1

Source title: Консольная утилита поиска и скачивания изображений для вызова ИИ-агентом

Contract asset: agent-architecture-handoff.v1.json

Contract SHA-256: 2556d39044bc87f828704b28f39f1b136761f18330c69c087a387f1ae69fa2bf

Workflow

  • Repository: projects/product-54354138-1
  • Repository intent: existing_repository
  • Base branch: master
  • Target branch: task/1-task
  • Facade: .agent/project.yaml (initialized)
  • CI: created
  • Created repository: false
  • Created branch: true
  • Facade template: script_toolkit_python
  • Facade action: initialize
  • Project shape: project_kind=script_toolkit, languages=['python'], runtimes=['command_line'], interfaces=['cli'], delivery_kind=native_process
  • Project shape requirement refs: project_kind=['REQ-001', 'REQ-011'], languages=['REQ-001', 'REQ-011'], runtimes=['REQ-001', 'REQ-011'], interfaces=['REQ-001', 'REQ-002', 'REQ-009'], delivery_kind=['REQ-011']
  • Facade placement: kind=repository_root

Architecture Plan

Context

Product request issue #1: a console (CLI) image search/download utility invoked by an AI agent via tool calling. Contract requirements REQ-001..REQ-011: parameters for topic, desired size, format (initial set png/ico), source, download flag and resize flag; machine-readable structured output distinguishing success / no-images-of-format / no-images-of-size / source-access error (AC-001, AC-011); free access without API keys or secrets (REQ-003, AC-002); pluggable source selection with explicit unknown-source error listing available sources (REQ-004, AC-003); only requested format returned and explicit "no images of this format" message distinct from access errors (REQ-007, AC-004); only images not smaller than the desired size in both dimensions, with actual dimensions reported (REQ-006, REQ-008, AC-005, AC-006); download into a caller-specified directory with reported paths (REQ-009, AC-007); downscale-only resizing behind a flag, unchanged dimensions without the flag (REQ-010, AC-008); live-source verification on a known topic (AC-010); delivered and run as a plain executable process with no Docker/containers (REQ-011, AC-009). Approved network access is Wikimedia Commons and Open

Decision

Shape: script_toolkit (Python 3, command_line runtime, cli interface, native_process delivery, repository_root placement). This is the narrowest catalog-template-backed shape that covers every resulting language, runtime, public interface and delivery form: the deliverable is one command-line program that speaks over argv/stdout, there is no HTTP server and no second language, and REQ-011/AC-009 forbid container delivery. 'file_io' is intentionally not declared as a separate public interface: writing downloaded files into the caller-specified directory (REQ-009) and reporting the resulting paths (REQ-002) is internal behavior of the CLI invocation, not an independent repository interface, and declaring it would leave the shape without a supported facade template. Facade: initialize (currently missing) at repository_root, since no product artifact fixes a component root. Implementation direction: a single Python CLI entry module parsed with argparse (topic, desired width/height, format png|ico, source, --count limit, --download, --output-dir, --resize), a small source-adapter registry (Wikimedia Commons MediaWiki API first, Openverse as a second adapter behind the same registry) so

Constraints

  • Project shape is limited to script_toolkit/Python/command_line/cli/native_process at repository_root; do not add an HTTP service, a second language or container packaging.
  • Delivery must be a plain executable process (REQ-011, AC-009): no Dockerfile, compose file or container entrypoint.
  • Only free, credential-free sources; no API keys, tokens, registration or secret configuration may be required or read at runtime (REQ-003, OOS-003).
  • Only Wikimedia Commons and Openverse over HTTPS 443 (incl. subdomains) are approved network destinations; no other hosts and no public-download fallbacks.
  • Format support limited to png and ico (REQ-007, OOS-002); no other formats and no editing beyond downscaling (OOS-001).
  • Output must remain a single machine-readable JSON document with distinct status values and matching exit codes for success, no-format, no-size, access error and invalid request (REQ-002, AC-001, AC-011).
  • Filters must be applied on the client side to the actual downloaded/parsed image data, not trusted from source metadata alone, so reported format and dimensions are real.
  • Resizing may only downscale to the desired size and must be off by default (REQ-010, AC-008).

Risks

  • UNK-001: it is unverified whether the chosen first source supports server-side filtering by size/format; if not, client-side filtering against REQ-008 may require downloading many candidates and could hit timeouts or rate limits, affecting REQ-007 and REQ-008 outcomes.
  • UNK-002: ico availability on free sources is unknown; the no-format path (REQ-007) may be the common outcome and must be proven to be distinct from access errors rather than assumed.
  • UNK-003: source rate limits and User-Agent/identification requirements are unverified and could turn normal usage into access errors, affecting REQ-003 and AC-011 behavior.
  • UNK-004: the default download directory when the caller omits it is an open product decision; either a mandatory --output-dir error or a documented default must be confirmed before REQ-009 is finalized.
  • UNK-005: partial download success reporting is an open product decision affecting REQ-009 and REQ-002 status semantics.
  • Pillow (or an equivalent decoder/resizer) availability in the internal Gitea catalog is unverified; if it is not published, ICO dimension verification and downscaling (REQ-007, REQ-010) cannot be satisfied with stdlib alone and must not be replaced by a public-download fallback.
  • Live-source reachability for AC-010 depends on runtime egress to the approved hosts; if the sandbox cannot reach them, that limitation must be recorded instead of substituting synthetic results.
  • Exit-code and status vocabulary must be fixed once and reused by all branches, otherwise AC-001/AC-006 distinguishability degrades.

Team Lead Handoff

  • First prove the smallest end-to-end public path on the live source: run the CLI for a known topic against Wikimedia Commons requesting png, observe a non-empty JSON list with working URLs and real dimensions (AC-010), then confirm the same run with no API key/credential env vars set (AC-002).
  • Bounded check for UNK-001: issue one documented MediaWiki/Openverse search request and record whether size/mime filtering is available server-side and how many candidates must be fetched to satisfy the >= size rule; the decision between server-side parameters and client-side-only filtering (and any candidate cap) depends on that observation.
  • Bounded check for UNK-003: run a handful of sequential requests and record response codes, any 429 behaviour and whether a custom User-Agent is required; the retry/backoff design and whether a --count cap is enforced client-side depend on the result.
  • Bounded check for UNK-002: query an ico request against the chosen source and record whether the no-format status is produced while the source is reachable; this decides how the no-format message is worded and which exit code is paired with it.
  • Bounded check for Pillow availability: attempt prepare_environment with the declared manifest and record whether Pillow resolves from the internal catalog; the choice between Pillow-based ICO decode/resize and a reduced, explicitly recorded capability depends on that result. If it is missing, request operator publication; do not add public index fallbacks or credential changes.
  • Decide and document UNK-004 and UNK-005 with the product owner before finalizing REQ-009 output: default download directory behaviour and the status/exit code for partial download success.
  • All dependency changes must go through the manifests and lock files declared by the generated facade and Tool Backend prepare_environment; agents must not change package sources, credentials, network access or admission policy, and any policy exception requires human approval.
  • Preserve required coverage: every status branch (success, no-format, no-size, access error, invalid/unknown source) needs its own executed check and matching exit code, and aggregate exit 0 must not be treated as proof that the no-format and no-size outcomes work.
<!-- agent-architecture-handoff {"asset": "agent-architecture-handoff.v1.json", "renderer": "agent.architecture_handoff_markdown.v1", "schema": "agent.architecture_handoff.v1", "sha256": "2556d39044bc87f828704b28f39f1b136761f18330c69c087a387f1ae69fa2bf"} --> Parent architecture issue: #1 Source title: Консольная утилита поиска и скачивания изображений для вызова ИИ-агентом Contract asset: `agent-architecture-handoff.v1.json` Contract SHA-256: `2556d39044bc87f828704b28f39f1b136761f18330c69c087a387f1ae69fa2bf` ## Workflow - Repository: projects/product-54354138-1 - Repository intent: existing_repository - Base branch: `master` - Target branch: `task/1-task` - Facade: `.agent/project.yaml` (`initialized`) - CI: `created` - Created repository: `false` - Created branch: `true` - Facade template: `script_toolkit_python` - Facade action: `initialize` - Project shape: `project_kind=script_toolkit, languages=['python'], runtimes=['command_line'], interfaces=['cli'], delivery_kind=native_process` - Project shape requirement refs: `project_kind=['REQ-001', 'REQ-011'], languages=['REQ-001', 'REQ-011'], runtimes=['REQ-001', 'REQ-011'], interfaces=['REQ-001', 'REQ-002', 'REQ-009'], delivery_kind=['REQ-011']` - Facade placement: `kind=repository_root` <!-- agent-provisioner:task base_branch=master target_branch=task/1-task --> <!-- architect-agent:plan mode=llm --> ## Architecture Plan ### Context Product request issue #1: a console (CLI) image search/download utility invoked by an AI agent via tool calling. Contract requirements REQ-001..REQ-011: parameters for topic, desired size, format (initial set png/ico), source, download flag and resize flag; machine-readable structured output distinguishing success / no-images-of-format / no-images-of-size / source-access error (AC-001, AC-011); free access without API keys or secrets (REQ-003, AC-002); pluggable source selection with explicit unknown-source error listing available sources (REQ-004, AC-003); only requested format returned and explicit "no images of this format" message distinct from access errors (REQ-007, AC-004); only images not smaller than the desired size in both dimensions, with actual dimensions reported (REQ-006, REQ-008, AC-005, AC-006); download into a caller-specified directory with reported paths (REQ-009, AC-007); downscale-only resizing behind a flag, unchanged dimensions without the flag (REQ-010, AC-008); live-source verification on a known topic (AC-010); delivered and run as a plain executable process with no Docker/containers (REQ-011, AC-009). Approved network access is Wikimedia Commons and Open ### Decision Shape: script_toolkit (Python 3, command_line runtime, cli interface, native_process delivery, repository_root placement). This is the narrowest catalog-template-backed shape that covers every resulting language, runtime, public interface and delivery form: the deliverable is one command-line program that speaks over argv/stdout, there is no HTTP server and no second language, and REQ-011/AC-009 forbid container delivery. 'file_io' is intentionally not declared as a separate public interface: writing downloaded files into the caller-specified directory (REQ-009) and reporting the resulting paths (REQ-002) is internal behavior of the CLI invocation, not an independent repository interface, and declaring it would leave the shape without a supported facade template. Facade: initialize (currently missing) at repository_root, since no product artifact fixes a component root. Implementation direction: a single Python CLI entry module parsed with argparse (topic, desired width/height, format png|ico, source, --count limit, --download, --output-dir, --resize), a small source-adapter registry (Wikimedia Commons MediaWiki API first, Openverse as a second adapter behind the same registry) so ### Constraints - Project shape is limited to script_toolkit/Python/command_line/cli/native_process at repository_root; do not add an HTTP service, a second language or container packaging. - Delivery must be a plain executable process (REQ-011, AC-009): no Dockerfile, compose file or container entrypoint. - Only free, credential-free sources; no API keys, tokens, registration or secret configuration may be required or read at runtime (REQ-003, OOS-003). - Only Wikimedia Commons and Openverse over HTTPS 443 (incl. subdomains) are approved network destinations; no other hosts and no public-download fallbacks. - Format support limited to png and ico (REQ-007, OOS-002); no other formats and no editing beyond downscaling (OOS-001). - Output must remain a single machine-readable JSON document with distinct status values and matching exit codes for success, no-format, no-size, access error and invalid request (REQ-002, AC-001, AC-011). - Filters must be applied on the client side to the actual downloaded/parsed image data, not trusted from source metadata alone, so reported format and dimensions are real. - Resizing may only downscale to the desired size and must be off by default (REQ-010, AC-008). ### Risks - UNK-001: it is unverified whether the chosen first source supports server-side filtering by size/format; if not, client-side filtering against REQ-008 may require downloading many candidates and could hit timeouts or rate limits, affecting REQ-007 and REQ-008 outcomes. - UNK-002: ico availability on free sources is unknown; the no-format path (REQ-007) may be the common outcome and must be proven to be distinct from access errors rather than assumed. - UNK-003: source rate limits and User-Agent/identification requirements are unverified and could turn normal usage into access errors, affecting REQ-003 and AC-011 behavior. - UNK-004: the default download directory when the caller omits it is an open product decision; either a mandatory --output-dir error or a documented default must be confirmed before REQ-009 is finalized. - UNK-005: partial download success reporting is an open product decision affecting REQ-009 and REQ-002 status semantics. - Pillow (or an equivalent decoder/resizer) availability in the internal Gitea catalog is unverified; if it is not published, ICO dimension verification and downscaling (REQ-007, REQ-010) cannot be satisfied with stdlib alone and must not be replaced by a public-download fallback. - Live-source reachability for AC-010 depends on runtime egress to the approved hosts; if the sandbox cannot reach them, that limitation must be recorded instead of substituting synthetic results. - Exit-code and status vocabulary must be fixed once and reused by all branches, otherwise AC-001/AC-006 distinguishability degrades. ### Team Lead Handoff - First prove the smallest end-to-end public path on the live source: run the CLI for a known topic against Wikimedia Commons requesting png, observe a non-empty JSON list with working URLs and real dimensions (AC-010), then confirm the same run with no API key/credential env vars set (AC-002). - Bounded check for UNK-001: issue one documented MediaWiki/Openverse search request and record whether size/mime filtering is available server-side and how many candidates must be fetched to satisfy the >= size rule; the decision between server-side parameters and client-side-only filtering (and any candidate cap) depends on that observation. - Bounded check for UNK-003: run a handful of sequential requests and record response codes, any 429 behaviour and whether a custom User-Agent is required; the retry/backoff design and whether a --count cap is enforced client-side depend on the result. - Bounded check for UNK-002: query an ico request against the chosen source and record whether the no-format status is produced while the source is reachable; this decides how the no-format message is worded and which exit code is paired with it. - Bounded check for Pillow availability: attempt prepare_environment with the declared manifest and record whether Pillow resolves from the internal catalog; the choice between Pillow-based ICO decode/resize and a reduced, explicitly recorded capability depends on that result. If it is missing, request operator publication; do not add public index fallbacks or credential changes. - Decide and document UNK-004 and UNK-005 with the product owner before finalizing REQ-009 output: default download directory behaviour and the status/exit code for partial download success. - All dependency changes must go through the manifests and lock files declared by the generated facade and Tool Backend prepare_environment; agents must not change package sources, credentials, network access or admission policy, and any policy exception requires human approval. - Preserve required coverage: every status branch (success, no-format, no-size, access error, invalid/unknown source) needs its own executed check and matching exit code, and aggregate exit 0 must not be treated as proof that the no-format and no-size outcomes work.
agent-architecture-handoff.v1.json
39 KiB
ai-architect added the auto:allowedrole:team-leadstatus:ready-for-lead labels 2026-11-02 22:37:37 +00:00
ai-dev added the claim:active label 2026-11-02 22:37:39 +00:00
ai-dev added status:in-lead and removed claim:activestatus:ready-for-lead labels 2026-11-02 22:44:48 +00:00
ai-team-lead commented 2026-11-02 22:45:07 +00:00
Member
Copy Link
Copy Source

teamlead-agent decomposed this handoff into developer issue(s): #3, #4, #5, #6, #7, #8, #9, #10.
Parent architecture issue: #1

<!-- teamlead-agent:done --> teamlead-agent decomposed this handoff into developer issue(s): #3, #4, #5, #6, #7, #8, #9, #10. Parent architecture issue: #1
ai-dev added status:done and removed role:team-leadstatus:in-lead labels 2026-11-02 22:45:07 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
auto:allowed
Autonomous agents may claim this issue when role and status labels match.
 claim:active
A non-expired agent claim exists in issue or pull request comments.
 needs:architecture
Requires architecture planning before implementation.
 role:architect
Turns architecture-marked proposals into ADR-like plans and lead-ready follow-up work.
 role:developer
Implements code and tests, opens PRs, and fixes CI failures.
 role:product-manager
Creates product proposals from ideas and feedback.
 role:reviewer
Reviews diffs, tests, CI reports, and returns or accepts work.
 role:team-lead
Clarifies scope, decomposes tasks, and gates development readiness.
 role:tester
Runs final product acceptance and creates developer bug follow-ups.
 status:accepted
Work passed review and can be reported or merged by the outer workflow.
 status:blocked
Automation cannot continue without human input.
 status:done
Workflow item is complete.
 status:draft-acceptance
Teamlead-agent has created a final acceptance task draft that is not claimable yet.
 status:draft-development
Teamlead-agent has created a developer task draft that is not claimable yet.
 status:idea
Raw user idea or feedback that has not been shaped yet.
 status:in-architecture
Architect is writing an ADR-like plan or lead follow-up.
 status:in-development
Developer is implementing or fixing the task.
 status:in-lead
Teamlead-agent is decomposing architecture into developer work.
 status:in-review
PR is ready for review after CI/deploy feedback.
 status:in-test
Tester-agent is running final product acceptance.
 status:needs-development
Review or CI found issues that must return to development.
 status:needs-test
Work needs final acceptance testing or retesting.
 status:proposed
Product proposal exists, but it is not ready for development.
 status:ready-for-architecture
Proposal needs architecture review before team lead planning.
 status:ready-for-development
Task is scoped and may be assigned to a developer.
 status:ready-for-lead
Proposal is ready for technical planning.
 status:ready-for-test
Merged product work is ready for final tester acceptance.
 status:waiting-for-acceptance
Final acceptance is waiting for all implementation dependencies to complete.
 status:waiting-for-dependency
Task is scoped but cannot be claimed until prerequisite child tasks are complete.
 type:bug
Broken or incorrect behavior.
No labels auto:allowed status:done
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ai-architect (AI Architect) ai-dev (AI Developer) ai-product-manager (AI Product Manager) ai-reviewer (AI Reviewer) ai-team-lead (AI Team Lead) ai-tester (AI Tester) labadmin rumxcola
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: projects/product-54354138-1#2