atm-backtesting/.claude/commands/batch.md

description, argument-hint

description	argument-hint
Run vision extraction in parallel on multiple screenshots (default screenshots/inbox/), then serial-append the results with partial-failure handling.	[dir_or_glob] [--limit N] [--calibration]

/batch — parallel vision extraction over multiple screenshots

Procesează screenshot-uri multiple. Lansează până la 5 subagenți m2d-extractor în paralel (cap rigid — protejează context window și rate limits). După ce toți revin, append-ezi rezultatele serial (append_row citește/scrie CSV — paralelism la write = corupție garantată).

Arguments

• $1 (opțional) — director sau glob. Default screenshots/inbox/. Exemplu: screenshots/inbox/2025-09-*.png.
• --limit N (opțional) — procesează doar primele N screenshot-uri (în ordine alfabetică). Default: toate.
• --calibration (flag) — source=vision_calibration în loc de vision.

Workflow

Fază 1 — Colectează lista

1. Enumeră fișierele PNG/JPG match-uind argumentul. Sortează alfabetic. Aplică --limit dacă există.
2. Dacă lista e goală → raportezi "Nimic de procesat în " și te oprești.
3. Dacă lista are 1 element → sugerează /backtest în loc și continuă cu batch.

Fază 2 — Extracție paralelă (max 5 concurent)

Procesezi în batch-uri de 5. Pentru fiecare batch:

• Lansezi câte un Task tool call cu subagent_type: "m2d-extractor" pentru fiecare screenshot, ÎN ACELAȘI MESAJ (tool calls paralele). Prompt-ul per agent:

  screenshot_path: <absolute_path>
  screenshot_file: <basename>
  

• Aștepți să se întoarcă toți cinci. Pentru fiecare, verifici că data/extractions/<basename_no_ext>.json a fost scris.

• Treci la următorul batch de 5.

De ce 5: peste 5 sub-agenți paraleli începi să saturezi context window-ul orchestratorului cu output-urile lor și rate limits-urile API-ului. Cap rigid.

Fază 3 — Append serial cu partial-failure

Pentru fiecare screenshot din lista originală, în ordine:

1. Verifică data/extractions/<basename_no_ext>.json:

   • Lipsă → log "missing JSON, agent abort", mută screenshot-ul la screenshots/needs_review/, continuă cu următorul.
   • Citește JSON. Dacă confidence == "low" SAU "image_unreadable" in ambiguities → mută la needs_review/, continuă.

2. Apelează append:

   python -c "from pathlib import Path; from scripts.append_row import append_extraction; import json; r = append_extraction(Path('data/extractions/<basename_no_ext>.json'), source='<source>'); print(json.dumps(r, default=str))"
   

   <source> = vision_calibration dacă --calibration, altfel vision.

3. Reacționezi la rezultat:

   • status == "ok" → ține minte ID-ul, mută screenshot la screenshots/processed/<basename> dacă era în inbox.
   • status == "rejected", reason conține "duplicate" → ține minte ca skip; NU muta screenshot-ul (deja procesat).
   • status == "rejected", alt reason → log motivul, mută la needs_review/.

4. NU oprești batch-ul la primul fail. Continuă până la capăt.

Fază 4 — Regenerează MD o singură dată

După ce toate append-urile s-au terminat (chiar și parțial), rulezi UNA SINGURĂ DATĂ:

python scripts/regenerate_md.py

(Regenerarea după fiecare append e wasteful; CSV-ul e sursa de adevăr, MD-ul e mirror.)

Fază 5 — Raport final

Format:

/batch terminat. Procesat <total> screenshot-uri.
  OK:           <n_ok>     (trade-uri #<id1>, #<id2>, ...)
  Duplicate:    <n_dup>    (skipped — deja în CSV)
  Needs review: <n_nr>     (mutate la screenshots/needs_review/)
    - <basename1>: <motiv>
    - <basename2>: <motiv>
  Erori:        <n_err>
    - <basename>: <reason>
Regenerat data/jurnal.md (<total_rows> rânduri).

Reguli

• Cap concurrency la 5. Niciodată mai mulți subagenți paraleli — chiar și pentru un batch mare. Procesezi în secvențe de batch-uri de 5.
• Append serial obligatoriu. append_extraction citește CSV-ul, computează next_id și scrie atomic; rulat în paralel ar duce la ID-uri duplicat sau pierderi.
• Partial failure = continuă. Un screenshot prost nu blochează restul batch-ului.
• MD regen o singură dată la final.
• Path discipline pentru subagent neschimbată: agentul scrie doar la data/extractions/. Tu, ca orchestrator, muți screenshot-uri.